com.soa.soap.message

Interface SOAPMessage

All Superinterfaces:

java.lang.Cloneable, Message

public interface SOAPMessage
extends Message, java.lang.Cloneable

Message interface extension specifically modelling SOAP messages.

Since:

3.1

Method Summary

Modifier and Type	Method and Description
java.lang.Object	clone() Performs a shallow copy of the SOAPMessage.
SOAPElement	createHeader(org.w3c.dom.Element value) Inserts the given Element as a SOAP header.
SOAPElement	createHeader(javax.xml.namespace.QName name) Creates an empty SOAP header holder that can be filled and then attached to the SOAP message using createHeader.
SOAPElement	createHeader(javax.xml.namespace.QName name, java.lang.String prefix) Creates an empty SOAP header holder that can be filled and then attached to the SOAP message using createHeader.
SOAPElement	getBody() Returns the body of the SOAP message.
SOAPPartsIterator	getBodyPartNames() Gets the names of the body parts of the message.
java.util.Iterator	getBodyParts() Get the body parts of the message as an iterator across all SOAPElements in the message.
javax.xml.transform.Source	getEnvelope() Returns a Source representation of the SOAP envelope.
SOAPElement	getHeader(javax.xml.namespace.QName name) Returns the SOAP header with the given eleemnt QName.
java.util.Set	getHeaderNames() Returns the names of all SOAP headers.
java.lang.String	getMessageName() Returns the name of the message in WSDL.
javax.xml.namespace.QName	getMessageType() Returns the QName of the schema type of the message.
java.lang.String	getStyle() Returns the encoding style, RPC or DOCUMENT, of the message.
java.lang.Object	getTransportProperty(java.lang.String propertyName) Returns the transport specific property with the given name.
SOAPVersion	getVersion() Returns the SOAP version.
boolean	hasChanged() Returns whether the message has changed since it was constructed.
boolean	isFault() Returns whether or not this SOAP message is a fault.
boolean	isVersionKnown() Returns whether the version of the message is known at this time.
SOAPElement	removeHeader(javax.xml.namespace.QName name) Removes the SOAP header with the given QName.
void	setEnvelope(javax.xml.transform.Source envelope) Replaces the SOAP envelope entirely.
void	setEnvelope(javax.xml.transform.Source envelope, SOAPVersion version) Replaces the SOAP envelope entirely.
void	setMessageName(java.lang.String messageName) Sets the name of the message in WSDL.
void	setMessageType(javax.xml.namespace.QName messageType) Sets the QName of the schema type of the message.
void	setPartNames(java.util.List<java.lang.String> partNames) Sets the names of the parts in the message.
void	setStyle(java.lang.String style) Sets the encoding style, RPC or DOCUMENT, of the message.
void	setTransportProperties(java.util.Map properties) Performs a one step replacement of transport properties.
void	setTransportProperty(java.lang.String propertyName, java.lang.Object property) Associates a transport specific property with the message.
void	setVersion(SOAPVersion version) Changes the version of the message.

Methods inherited from interface com.soa.message.Message

addAttachment, addPart, arePartsEmpty, canCarryBindingHeaders, canNormalize, copy, getAttachments, getBindingURI, getContent, getContentPartName, getContentType, getCorrelationID, getID, getPart, getPartNames, getParts, getProperties, getProperty, getPropertyNames, getSecuritySubject, getTransportHeaders, isNormalized, normalize, normalizeCopy, normalizeCopyToXML, normalizeToXML, setAttachments, setContent, setContentPartName, setContentType, setCorrelationID, setID, setProperties, setProperty, setSecuritySubject, setTransportHeaders

Method Detail

isVersionKnown

boolean isVersionKnown()

Returns whether the version of the message is known at this time. If the message has been configured with an entire envelope that hasn't been parsed and no version has been specified previously it would not be safe to assume a version and therefore the version would be unknown.

Returns:

true if known, false if not.

getVersion

SOAPVersion getVersion()
                throws GException

Returns the SOAP version. If the version is unknown (see isVersionKnown) calling this method may require parsing of the message.

Throws:

GException - Thrown if parsing was required to find the version and an error was encountered during that process.

setVersion

void setVersion(SOAPVersion version)
         throws GException

Changes the version of the message. WARNING: this must only be called when the version of the message is currently unknown. Changing the known version will case an error.

Parameters:

version - SOAPVersion.

Throws:

GException - Thrown if an attempt is made to change the known version of the message.

getBody

SOAPElement getBody()
             throws GException

Returns the body of the SOAP message.

Returns:

SOAPElement holding the body content.

Throws:

GException - Thrown if unable to return the body. Maybe be caused by a badly formed SOAP message.

getBodyParts

java.util.Iterator getBodyParts()
                         throws GException

Get the body parts of the message as an iterator across all SOAPElements in the message. Use of an Iterator allow the internal implementation to parse on demand, allowing for potentially better performance characteristics than getBody().

Returns:

An Iterator over all SOAPElements in the SOAP Body.

Throws:

GException - Thrown if unable to return the parts. Maybe caused by a badly formed SOAP message.

getBodyPartNames

SOAPPartsIterator getBodyPartNames()
                            throws GException

Gets the names of the body parts of the message. Names are returned in an Iterator to support on-demand parsing for high performance.

Returns:

Iterator of body part QNames. The Iterator MUST be closed to release the message resources before any other methods on this object can be called.

Throws:

GException - Thrown if unable to return the part names. Maybe caused by a badly formed SOAP message.

createHeader

SOAPElement createHeader(javax.xml.namespace.QName name)
                  throws GException

Creates an empty SOAP header holder that can be filled and then attached to the SOAP message using createHeader.

Parameters:

QName - QName of the header element.

Returns:

SOAPElement that will hold the SOAP header.

Throws:

GException - if unable to create the header.

createHeader

SOAPElement createHeader(javax.xml.namespace.QName name,
                         java.lang.String prefix)
                  throws GException

Creates an empty SOAP header holder that can be filled and then attached to the SOAP message using createHeader. This version of the method takes an additional prefix that will be used for the namespace of the header's QName.

Parameters:

name - QName of the header element.

prefix - Prefix of the header's namespace.

Returns:

SOAPElement that will hold the SOAP header.

Throws:

GException - if unable to create the header.

createHeader

SOAPElement createHeader(org.w3c.dom.Element value)
                  throws GException

Inserts the given Element as a SOAP header.

Parameters:

value - Element to be used as header.

Returns:

SOAPElement holding the header Element.

Throws:

GException - Thrown if unable to create the header.

getHeader

SOAPElement getHeader(javax.xml.namespace.QName name)
               throws GException

Returns the SOAP header with the given eleemnt QName.

Parameters:

name - QName of the header to return.

Returns:

SOAPElement holding the SOAP header, null if not found.

Throws:

GException - Thrown if an error occured trying to return the header. Probably due to a badly formed SOAP message.

removeHeader

SOAPElement removeHeader(javax.xml.namespace.QName name)
                  throws GException

Removes the SOAP header with the given QName.

Parameters:

name - QName of the header to remove.

Returns:

SOAPElement holding the removed SOAP header content, null if not found.

Throws:

GException - Thrown if unable to remove the header. Probably due to a badly formed SOAP message.

getHeaderNames

java.util.Set getHeaderNames()
                      throws GException

Returns the names of all SOAP headers.

Returns:

Set of SOAP header QNames. Changes made to the Set are reflected in the message, so if a name is removed from the Set, the header is removed from the message. Names cannot be added however.

Throws:

GException - Thrown if unable to return the list. Probably due to a badly formed SOAP message.

getTransportProperty

java.lang.Object getTransportProperty(java.lang.String propertyName)

Returns the transport specific property with the given name.

Parameters:

propertyName - Name of the property.

Returns:

Object value of the transport property, null if not found.

setTransportProperty

void setTransportProperty(java.lang.String propertyName,
                          java.lang.Object property)

Associates a transport specific property with the message. All transport properties added through this interface will also be available through the more general getProperty() method as a Map with a key of "com.soa.soap.message.TransportProperties".

Parameters:

propertyName - Name of the transport specific property.

property - Value of the property.

setTransportProperties

void setTransportProperties(java.util.Map properties)

Performs a one step replacement of transport properties. All transport properties added through this interface will also be available through the more general getProperty() method as a Map with a key of "com.soa.soap.message.TransportProperties".

Parameters:

properties - Map of transport properties.

hasChanged

boolean hasChanged()

Returns whether the message has changed since it was constructed.

Returns:

True if it has changed, false if it has not.

getEnvelope

javax.xml.transform.Source getEnvelope()
                                throws GException

Returns a Source representation of the SOAP envelope. WARNING: Do not make changes directly to the returned Source object without calling setEnvelope().

Returns:

Source holding the entire SOAP envelope.

Throws:

GException - Thrown if unable to create the Source. Probably due to a badly formed SOAP message.

setEnvelope

void setEnvelope(javax.xml.transform.Source envelope)
          throws GException

Replaces the SOAP envelope entirely. Any modifications done through the header and body methods previously will be lost. Since the envelope could be from a different SOAP version than previously stated, the version of the message will be invalidated. To identify the version of the message, the envelope will have to be parsed. If the version of the envelope is known use setEnvelope(Source, SOAPVersion) instead.

Parameters:

envelope - Source holding the new SOAP envelope.

Throws:

GException - Thrown if unable to replace the envelope. Most likely due to an invalid SOAP envelope being input.

setEnvelope

void setEnvelope(javax.xml.transform.Source envelope,
                 SOAPVersion version)
          throws GException

Replaces the SOAP envelope entirely. Any modifications done through the header and body methods previously will be lost. The version of the envelope will be changed to the specified version.

Parameters:

envelope - Source holding the new SOAP envelope.

version - SOAP version of the envelope.

Throws:

GException - Thrown if unable to replace the envelope. Most likely due to an invalid SOAP envelope being input.

isFault

boolean isFault()
         throws GException

Returns whether or not this SOAP message is a fault.

Specified by:

isFault in interface Message

Returns:

true if SOAP fault, false if not.

Throws:

GException - Thrown if unable to determine if the message is a fault. Probably due to a badly formed SOAP message.

setStyle

void setStyle(java.lang.String style)

Sets the encoding style, RPC or DOCUMENT, of the message.

Parameters:

style - RPC or DOCUMENT.

getStyle

java.lang.String getStyle()

Returns the encoding style, RPC or DOCUMENT, of the message.

Returns:

RCP or DOCUMENT.

setMessageType

void setMessageType(javax.xml.namespace.QName messageType)

Sets the QName of the schema type of the message. Used in RPC style messages.

Parameters:

messageType - QName of the schema type.

setPartNames

void setPartNames(java.util.List<java.lang.String> partNames)

Sets the names of the parts in the message. Used in RPC style messages.

Parameters:

partNames - List of part names.

getMessageType

javax.xml.namespace.QName getMessageType()

Returns the QName of the schema type of the message. Used in RPC style messages.

Returns:

QName of the schema type.

setMessageName

void setMessageName(java.lang.String messageName)

Sets the name of the message in WSDL. Used in RPC style messages.

Parameters:

messageName - Name of the message.

getMessageName

java.lang.String getMessageName()

Returns the name of the message in WSDL. Used in RPC style messages.

Returns:

Name of the message.

clone

java.lang.Object clone()

Performs a shallow copy of the SOAPMessage.

Returns:

Copy of the SOAPMessage.