org.apache.tsik.messaging
Class SoapMessage

java.lang.Object
  org.apache.tsik.messaging.SoapMessage

public class SoapMessage

extends Object

Provides SOAP message processing.

When used for implementing a web service, this class is the complement of the XmlTransportSoap class used for implementing web service clients. It is also possible to use SoapMessage directly for implementing a web service client, gateway, or SOAP router, without using XmlTransportSoap.

There are two ways of processing SOAP message security information:

• use the MessageSecurity object, which provides a somewhat simplified way of signing/encrypting the entire SOAP message
• use the WsHandler processing mechanism, where each element in the SOAP message will be fed through the processing callback mechanism.

.

Field Summary

static String	VERSION_1_1 TODO javadoc.
static String	VERSION_1_2 TODO javadoc.
static String	VERSION_1_2_2002_12 TODO javadoc.

Constructor Summary

SoapMessage(Document doc)
Creates a SOAP message object for a given SOAP document, wrapping the document in a SOAP 1.1 envelope if it doesn't already have one.

SoapMessage(Document doc, String version)
Creates a SOAP message object for a given SOAP document, wrapping the document in a SOAP envelope if it doesn't already have one.

Method Summary

void	addBody(Element bodyBlock) Adds the given body block element as the last child of the SOAP Body element.
void	addHeader(Element headerBlock) Adds a SOAP header block before any existing header blocks.
Document	extractBody() Returns a copy of the first child element of the SOAP Body which is not a fault element.
Element	getBody() Returns the first child element of the SOAP Body which is not a fault element.
Document	getDocument() Returns the SOAP message document.
SoapFault	getFault() Returns the SOAP fault contained in this message.
WsHandler[]	getHandlers() Returns the handlers, not a copy.
Element	getHeader(String namespaceURI, String localName) Returns a SOAP header block contained in this message.
Element[]	getHeaders() Returns all SOAP header blocks contained in this message.
boolean	getMustUnderstand(Element header) Returns whether the mustUnderstand attribute is set to true on a header element.
static String	getSoapVersion(Document doc) Returns the SOAP version (envelope namespace) of the given document, or null if the document element is not a SOAP Envelope.
static String	getSoapVersion(DOMCursor c) Returns the SOAP version (envelope namespace) of the element at the given cursor, or null if the element is not a SOAP Envelope.
static String	getSoapVersion(DOMCursor c, boolean translate) Translates 2002_12 into 2003_05 if requested.
static String	getSoapVersion(String uri) Returns the SOAP version constant for the given namespace, or null if the namespace is not a SOAP Envelope namespace.
static String	getSoapVersion(String uri, boolean translate) Returns the actual namespace URI, that is, if translation is requested 2002_12 will be returned if it is the SOAP version.
String	getVersion() Returns the SOAP version of the message: VERSION_1_1 or VERSION_1_2.
static boolean	isSoapMessage(Document doc) Tests whether a document's root element is the SOAP Envelope element.
void	process() Processes the SOAP message with the set of WsHandlers.
void	setFault(SoapFault fault) Adds the given SOAP fault under the SOAP Body element.
void	setHeaders(Element[] headerBlocks) Sets the specified SOAP header blocks, after deleting any existing header blocks.
void	setMustUnderstand(Element header, boolean mustUnderstand) Sets or clears the mustUnderstand attribute on a header element.
void	use(WsHandler[] wsHandlers) TODO javadoc.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VERSION_1_1

public static final String VERSION_1_1

TODO javadoc.

VERSION_1_2

public static final String VERSION_1_2

TODO javadoc.

VERSION_1_2_2002_12

public static final String VERSION_1_2_2002_12

TODO javadoc.

Constructor Detail

SoapMessage

public SoapMessage(Document doc)

Creates a SOAP message object for a given SOAP document, wrapping the document in a SOAP 1.1 envelope if it doesn't already have one.

Parameters:

doc - is a document whose document element is a SOAP envelope or a body element to be wrapped in a SOAP envelope and SOAP body. This document will be modified so the user must clone the document if they need to keep an unmodified copy of it. If the document is empty then the SOAP body will also be empty.

SoapMessage

public SoapMessage(Document doc,
                   String version)

Creates a SOAP message object for a given SOAP document, wrapping the document in a SOAP envelope if it doesn't already have one.

Parameters:

doc - is a document whose document element is a SOAP envelope or a body element to be wrapped in a SOAP envelope and SOAP body. This document will be modified so the user must clone the document if they need to keep an unmodified copy of it. If the document is empty then the SOAP body will also be empty.

version - is the SOAP version to use in the case where the given document does not have a SOAP envelope: VERSION_1_1 or VERSION_1_2.

Method Detail

use

public void use(WsHandler[] wsHandlers)

TODO javadoc.

Parameters:

wsHandlers - TODO.

getHandlers

public WsHandler[] getHandlers()

Returns the handlers, not a copy.

Returns:

TODO.

process

public void process()

Processes the SOAP message with the set of WsHandlers. This process mechanism does not use the MessageSecurity.

isSoapMessage

public static boolean isSoapMessage(Document doc)

Tests whether a document's root element is the SOAP Envelope element. This can be used by services to determine whether to process a request message using the SoapMessage class.

Parameters:

doc - the document containing the SOAP Envelope.

Returns:

whether a document's root element is the SOAP Envelope element.

getSoapVersion

public static String getSoapVersion(Document doc)

Returns the SOAP version (envelope namespace) of the given document, or null if the document element is not a SOAP Envelope.

Parameters:

doc - the document containing the SOAP Envelope.

Returns:

VERSION_1_1 or VERSION_1_2.

getSoapVersion

public static String getSoapVersion(DOMCursor c)

Returns the SOAP version (envelope namespace) of the element at the given cursor, or null if the element is not a SOAP Envelope.

Parameters:

c - the cursor pointing at the SOAP Envelope.

Returns:

VERSION_1_1 or VERSION_1_2.

getSoapVersion

public static String getSoapVersion(DOMCursor c,
                                    boolean translate)

Translates 2002_12 into 2003_05 if requested.

Parameters:

c - the cursor pointing at the SOAP Envelope.

translate - if true; VERSION_1_2_2002_12 will be returned as VERSION_1_2; otherwise as VERSION_1_2_2002_12.

Returns:

VERSION_1_1 or VERSION_1_2.

getSoapVersion

public static String getSoapVersion(String uri)

Returns the SOAP version constant for the given namespace, or null if the namespace is not a SOAP Envelope namespace.

Parameters:

uri - is the URI to parse. (Note that http://www.w3.org/2002/12/soap-envelope will be returned as VERSION_1_2.)

Returns:

VERSION_1_1 or VERSION_1_2.

getSoapVersion

public static String getSoapVersion(String uri,
                                    boolean translate)

Returns the actual namespace URI, that is, if translation is requested 2002_12 will be returned if it is the SOAP version.

Parameters:

uri - the namespace URI.

translate - if true; VERSION_1_2_2002_12 will be returned as VERSION_1_2; otherwise as VERSION_1_2_2002_12.

Returns:

VERSION_1_1 or VERSION_1_2.

getDocument

public Document getDocument()

Returns the SOAP message document. This is original Document object passed to the constructor, but may have been modified by envelope creation, signing, encryption or decryption.

Returns:

the SOAP message document.

getVersion

public String getVersion()

Returns the SOAP version of the message: VERSION_1_1 or VERSION_1_2. A reference to one of these version constants is always returned, so that it may be compared to the constants using ==.

Returns:

the version.

setHeaders

public void setHeaders(Element[] headerBlocks)

Sets the specified SOAP header blocks, after deleting any existing header blocks. The SOAP Header element will be created if necessary.

Parameters:

headerBlocks - is an array of SOAP header block elements conforming to the SOAP specification, or null if all header blocks are to be cleared.

addHeader

public void addHeader(Element headerBlock)

Adds a SOAP header block before any existing header blocks. The SOAP Header element will be created if necessary.

Parameters:

headerBlock - is a SOAP header block element conforming to the SOAP specification.

getHeaders

public Element[] getHeaders()

Returns all SOAP header blocks contained in this message.

Returns:

the array of SOAP header block elements.

getHeader

public Element getHeader(String namespaceURI,
                         String localName)

Returns a SOAP header block contained in this message.

Parameters:

namespaceURI - is the namespace of the element to be returned. A namespace is required for all SOAP header blocks.

localName - is the local name of the element to be returned. The local name does not include the namespace prefix.

Returns:

the SOAP header block element, or null if a header with the specified namespace and element name is not found.

setMustUnderstand

public void setMustUnderstand(Element header,
                              boolean mustUnderstand)

Sets or clears the mustUnderstand attribute on a header element.

The attribute value for true is 'true' for a SOAP 1.2 message and '1' for a SOAP 1.1 message.

Parameters:

header - is a SOAP header element of any type.

mustUnderstand - is true to set the attribute or false to remove the attribute.

getMustUnderstand

public boolean getMustUnderstand(Element header)

Returns whether the mustUnderstand attribute is set to true on a header element.

The attribute value for true is 'true' for a SOAP 1.2 message and '1' for a SOAP 1.1 message.

Parameters:

header - is a SOAP header element of any type.

Returns:

true if the must understand attribute exists and is set, false otherwise.

setFault

public void setFault(SoapFault fault)

Adds the given SOAP fault under the SOAP Body element. Any existing fault element will first be deleted.

Parameters:

fault - is the SOAP fault to add, or null to delete the existing fault only.

getFault

public SoapFault getFault()

Returns the SOAP fault contained in this message.

Returns:

the SOAP fault, or null if no fault is present.

addBody

public void addBody(Element bodyBlock)

Adds the given body block element as the last child of the SOAP Body element.

Parameters:

bodyBlock - is the body block to add.

getBody

public Element getBody()

Returns the first child element of the SOAP Body which is not a fault element.

Returns:

the first non-fault body block, or null if none is present. The returned element is not copied/extracted from the SOAP document.

extractBody

public Document extractBody()

Returns a copy of the first child element of the SOAP Body which is not a fault element. The element is extracted in such a way that the namespaces defined in SOAP envelope are not included (unless they are also defined in the body).

Returns:

a new document containing a copy of the first non-fault body block, or null if none is present.