javax.xml.soap
Interface SOAPHeader

All Superinterfaces:

org.w3c.dom.Element, org.w3c.dom.Node, SOAPElement

addNotUnderstoodHeaderElement

SOAPHeaderElement addNotUnderstoodHeaderElement(javax.xml.namespace.QName name)
                                                throws SOAPException

Creates a new NotUnderstood SOAPHeaderElement object initialized with the specified name and adds it to this SOAPHeader object. This operation is supported only by SOAP 1.2.

Parameters:

name - a QName object with the name of the SOAPHeaderElement object that was not understood.

Returns:

the new SOAPHeaderElement object that was inserted into this SOAPHeader object

Throws:

SOAPException - if a SOAP error occurs.

java.lang.UnsupportedOperationException - if this is a SOAP 1.1 Header.

Since:

SAAJ 1.3

addUpgradeHeaderElement

SOAPHeaderElement addUpgradeHeaderElement(java.util.Iterator supportedSOAPURIs)
                                          throws SOAPException

Creates a new Upgrade SOAPHeaderElement object initialized with the specified List of supported SOAP URIs and adds it to this SOAPHeader object. This operation is supported on both SOAP 1.1 and SOAP 1.2 header.

Parameters:

supportedSOAPURIs - an Iterator object with the URIs of SOAP versions supported.

Returns:

the new SOAPHeaderElement object that was inserted into this SOAPHeader object

Throws:

SOAPException - if a SOAP error occurs.

Since:

SAAJ 1.3

addUpgradeHeaderElement

SOAPHeaderElement addUpgradeHeaderElement(java.lang.String[] supportedSoapUris)
                                          throws SOAPException

Creates a new Upgrade SOAPHeaderElement object initialized with the specified array of supported SOAP URIs and adds it to this SOAPHeader object. This operation is supported on both SOAP 1.1 and SOAP 1.2 header.

Parameters:

supportedSoapUris - an array of the URIs of SOAP versions supported.

Returns:

the new SOAPHeaderElement object that was inserted into this SOAPHeader object

Throws:

SOAPException - if a SOAP error occurs.

Since:

SAAJ 1.3

addUpgradeHeaderElement

SOAPHeaderElement addUpgradeHeaderElement(java.lang.String supportedSoapUri)
                                          throws SOAPException

Creates a new Upgrade SOAPHeaderElement object initialized with the specified supported SOAP URI and adds it to this SOAPHeader object. This operation is supported on both SOAP 1.1 and SOAP 1.2 header.

Parameters:

supportedSoapUri - the URI of SOAP the version that is supported.

Returns:

the new SOAPHeaderElement object that was inserted into this SOAPHeader object

Throws:

SOAPException - if a SOAP error occurs.

Since:

SAAJ 1.3

javax.xml.soap
Interface SOAPHeaderElement

setRole

void setRole(java.lang.String uri)
             throws SOAPException

Sets the Role associated with this SOAPHeaderElement object to the specified Role.

Parameters:

uri - - the URI of the Role

Throws:

SOAPException - if there is an error in setting the role

java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Role.

Since:

SAAJ 1.3

getRole

java.lang.String getRole()

Returns the value of the Role attribute of this SOAPHeaderElement.

Returns:

a String giving the URI of the Role

Throws:

java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Role.

Since:

SAAJ 1.3

setRelay

void setRelay(boolean relay) throws SOAPException

Sets the relay attribute for this SOAPHeaderElement to be either true or false.

The SOAP relay attribute is set to true to indicate that the SOAP header block must be relayed by any node that is targeted by the header block but not actually process it. This attribute is ignored on header blocks whose mustUnderstand attribute is set to true or that are targeted at the ultimate receiver (which is the default). The default value of this attribute is false.

Parameters:

relay - the new value of the relay attribute

Throws:

SOAPException  - if there is a problem setting the relay attribute.

java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Relay attribute.

Since:

SAAJ 1.3

See Also:

setMustUnderstand(boolean), getRelay()

getRelay

boolean getRelay()

Returns the boolean value of the relay attribute for this SOAPHeaderElement

Returns:

true if the relay attribute is turned on; false otherwise

Throws:

java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of  Relay attribute.

Since:

SAAJ 1.3

See Also:

getMustUnderstand(), setRelay(boolean)

javax.xml.soap
Interface SOAPConstants

DYNAMIC_SOAP_PROTOCOL

static final java.lang.String DYNAMIC_SOAP_PROTOCOL

Used to create MessageFactory instances that create SOAPMessages whose concrete type is based on the content-type MIME header passed to the createMessage method. If no content-type header is passed then the createMessage may throw an IllegalArgumentException or, in the case of the no argument version of createMessage, an UnsupportedOperationException.

Since:

SAAJ 1.3

See Also:

Constant Field Values

SOAP_1_1_PROTOCOL

static final java.lang.String SOAP_1_1_PROTOCOL

Used to create MessageFactory instances that create SOAPMessages whose behavior supports the SOAP 1.1 specification.

Since:

SAAJ 1.3

See Also:

Constant Field Values

SOAP_1_2_PROTOCOL

static final java.lang.String SOAP_1_2_PROTOCOL

Used to create MessageFactory instances that create SOAPMessages whose behavior supports the SOAP 1.2 specification

Since:

SAAJ 1.3

See Also:

Constant Field Values

DEFAULT_SOAP_PROTOCOL

static final java.lang.String DEFAULT_SOAP_PROTOCOL

The default protocol: SOAP 1.1 for backwards compatibility.

Since:

SAAJ 1.3

See Also:

Constant Field Values

URI_NS_SOAP_1_1_ENVELOPE

static final java.lang.String URI_NS_SOAP_1_1_ENVELOPE

The namespace identifier for the SOAP 1.1 envelope.

Since:

SAAJ 1.3

See Also:

Constant Field Values

URI_NS_SOAP_1_2_ENVELOPE

static final java.lang.String URI_NS_SOAP_1_2_ENVELOPE

The namespace identifier for the SOAP 1.2 envelope.

Since:

SAAJ 1.3

See Also:

Constant Field Values

URI_NS_SOAP_1_2_ENCODING

static final java.lang.String URI_NS_SOAP_1_2_ENCODING

The namespace identifier for the SOAP 1.2 encoding.

Since:

SAAJ 1.3

See Also:

Constant Field Values

SOAP_1_1_CONTENT_TYPE

static final java.lang.String SOAP_1_1_CONTENT_TYPE

The media type of the Content-Type MIME header in SOAP 1.1.

Since:

SAAJ 1.3

See Also:

Constant Field Values

SOAP_1_2_CONTENT_TYPE

static final java.lang.String SOAP_1_2_CONTENT_TYPE

The media type of the Content-Type MIME header in SOAP 1.2.

Since:

SAAJ 1.3

See Also:

Constant Field Values

URI_SOAP_1_2_ROLE_NEXT

static final java.lang.String URI_SOAP_1_2_ROLE_NEXT

The URI identifying the next application processing a SOAP request as the intended role for a SOAP 1.2 header entry (see section 2.2 of part 1 of the SOAP 1.2 specification).

Since:

SAAJ 1.3

See Also:

Constant Field Values

URI_SOAP_1_2_ROLE_NONE

static final java.lang.String URI_SOAP_1_2_ROLE_NONE

The URI specifying the role None in SOAP 1.2.

Since:

SAAJ 1.3

See Also:

Constant Field Values

URI_SOAP_1_2_ROLE_ULTIMATE_RECEIVER

static final java.lang.String URI_SOAP_1_2_ROLE_ULTIMATE_RECEIVER

The URI identifying the ultimate receiver of the SOAP 1.2 message.

Since:

SAAJ 1.3

See Also:

Constant Field Values

SOAP_ENV_PREFIX

static final java.lang.String SOAP_ENV_PREFIX

The default namespace prefix for http://www.w3.org/2003/05/soap-envelope

Since:

SAAJ 1.3

See Also:

Constant Field Values

javax.xml.soap
Interface SOAPFault

getFaultSubcodes

java.util.Iterator getFaultSubcodes()

Gets the Subcodes for this SOAPFault as an iterator over QNames.

Returns:

an Iterator that accesses a sequence of QNames. This Iterator should not support the optional remove method. The order in which the Subcodes are returned reflects the hierarchy of Subcodes present in the fault from top to bottom.

Throws:

java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Subcode.

Since:

SAAJ 1.3

removeAllFaultSubcodes

void removeAllFaultSubcodes()

Removes any Subcodes that may be contained by this SOAPFault. Subsequent calls to getFaultSubcodes will return an empty iterator until a call to appendFaultSubcode is made.

Throws:

java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Subcode.

Since:

SAAJ 1.3

appendFaultSubcode

public void appendFaultSubcode(javax.xml.namespace.QName subcode)
                        throws SOAPException

Adds a Subcode to the end of the sequence of Subcodes contained by this SOAPFault. Subcodes, which were introduced in SOAP 1.2, are represented by a recursive sequence of subelements rooted in the mandatory Code subelement of a SOAP Fault.

Parameters:

subcode - a QName containing the Value of the Subcode.

Throws:

SOAPException - if there was an error in setting the Subcode

java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Subcode.

Since:

SAAJ 1.3

getFaultReasonLocales

public java.util.Iterator getFaultReasonLocales()
                                         throws SOAPException

Returns an Iterator over a distinct sequence of Locales for which there are associated Reason Text items. Any of these Locales can be used in a call to getFaultReasonText in order to obtain a localized version of the Reason Text string.

Returns:

an Iterator over a sequence of Locale objects for which there are associated Reason Text items.

Throws:

SOAPException - if there was an error in retrieving the fault Reason locales.

java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Reason.

Since:

SAAJ 1.3

getFaultReasonTexts

public java.util.Iterator getFaultReasonTexts()
                                       throws SOAPException

Returns an Iterator over a sequence of String objects containing all of the Reason Text items for this SOAPFault.

Returns:

an Iterator over env:Fault/env:Reason/env:Text items.

Throws:

SOAPException - if there was an error in retrieving the fault Reason texts.

java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Reason.

Since:

SAAJ 1.3

getFaultReasonText

public java.lang.String getFaultReasonText(java.util.Locale locale)
                                    throws SOAPException

Returns the Reason Text associated with the given Locale. If more than one such Reason Text exists the first matching Text is returned

Parameters:

locale - -- the Locale for which a localized Reason Text is desired

Returns:

the Reason Text associated with locale

Throws:

SOAPException - if there was an error in retrieving the fault Reason text for the specified locale .

java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Reason.

Since:

SAAJ 1.3

See Also:

getFaultString()

addFaultReasonText

public void addFaultReasonText(java.lang.String text,
                               java.util.Locale locale)
                        throws SOAPException

Appends or replaces a Reason Text item containing the specified text message and an xml:lang derived from locale. If a Reason Text item with this xml:lang already exists its text value will be replaced with text. The locale parameter should not be null

Code sample:

 SOAPFault fault = ...;
 fault.addFaultReasonText("Version Mismatch", Locale.ENGLISH);
 

Parameters:

text - -- reason message string

locale - -- Locale object representing the locale of the message

Throws:

SOAPException - if there was an error in adding the Reason text or the locale passed was null.

java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Reason.

Since:

SAAJ 1.3

getFaultNode

java.lang.String getFaultNode()

Returns the optional Node element value for this SOAPFault object. The Node element is optional in SOAP 1.2.

Returns:

Content of the env:Fault/env:Node element as a String or null if none

Throws:

java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Node.

Since:

SAAJ 1.3

setFaultNode

public void setFaultNode(java.lang.String uri)
                  throws SOAPException

Creates or replaces any existing Node element value for this SOAPFault object. The Node element is optional in SOAP 1.2.

Throws:

SOAPException - if there was an error in setting the Node for this SOAPFault object.

java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Node.

Since:

SAAJ 1.3

getFaultRole

public java.lang.String getFaultRole()

Returns the optional Role element value for this SOAPFault object. The Role element is optional in SOAP 1.2.

Returns:

Content of the env:Fault/env:Role element as a String or null if none

Throws:

java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Role.

Since:

SAAJ 1.3

setFaultRole

public void setFaultRole(java.lang.String uri)
                  throws SOAPException

Creates or replaces any existing Role element value for this SOAPFault object. The Role element is optional in SOAP 1.2.

Parameters:

uri - - the URI of the Role

Throws:

SOAPException - if there was an error in setting the Role for this SOAPFault object.

java.lang.UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Role.

Since:

SAAJ 1.3

hasDetail

boolean hasDetail()

Returns true if this SOAPFault has a Detail subelement and false otherwise. Equivalent to (getDetail()!=null).

Returns:

true if this SOAPFault has a Detail subelement and false otherwise.

Since:

SAAJ 1.3

newInstance

public static MessageFactory newInstance(java.lang.String protocol)
                                  throws SOAPException

Creates a new MessageFactory object that is an instance of the specified implementation. May be a dynamic message factory, a SOAP 1.1 message factory, or a SOAP 1.2 message factory. A dynamic message factory creates messages based on the MIME headers specified as arguments to the createMessage method.   This method uses the  SAAJMetaFactory to locate the implementation class and create the MessageFactory instance.

Parameters:

protocol - a string constant representing the class of the specified message factory implementation. May be either DYNAMIC_SOAP_PROTOCOL, DEFAULT_SOAP_PROTOCOL (which is the same as) SOAP_1_1_PROTOCOL, or SOAP_1_2_PROTOCOL.

Returns:

a new instance of a MessageFactory

Throws:

SOAPException - if there was an error in creating the specified implementation of MessageFactory.

See Also:

SAAJMetaFactory

Since:

SAAJ 1.3

javax.xml.soap
Class SOAPFactory

java.lang.Object
  javax.xml.soap.SOAPFactory

newInstance

Creates a new SOAPFactory object that is an instance of the specified implementation,  this method  uses the SAAJMetaFactory to locate the implementation class and create the SOAPFactory instance.

Parameters:

protocol - a string constant representing the protocol of the specified SOAP factory implementation. May be either  DYNAMIC_SOAP_PROTOCOL, DEFAULT_SOAP_PROTOCOL (which is the same as) SOAP_1_1_PROTOCOL, or SOAP_1_2_PROTOCOL.

Returns:

a new instance of a SOAPFactory

Throws:

SOAPException - if there was an error creating the specified SOAPFactory

See Also:

SAAJMetaFactory

Since:

SAAJ 1.3

javax.xml.soap
Interface SOAPConstants

SOAP_VERSIONMISMATCH_FAULT

static final javax.xml.namespace.QName SOAP_VERSIONMISMATCH_FAULT

SOAP 1.2 VersionMismatch Fault

Since:

SAAJ 1.3

SOAP_MUSTUNDERSTAND_FAULT

static final javax.xml.namespace.QName SOAP_MUSTUNDERSTAND_FAULT

SOAP 1.2 MustUnderstand Fault

Since:

SAAJ 1.3

SOAP_DATAENCODINGUNKNOWN_FAULT

static final javax.xml.namespace.QName SOAP_DATAENCODINGUNKNOWN_FAULT

SOAP 1.2 DataEncodingUnknown Fault

Since:

SAAJ 1.3

SOAP_SENDER_FAULT

static final javax.xml.namespace.QName SOAP_SENDER_FAULT

SOAP 1.2 Sender Fault

Since:

SAAJ 1.3

SOAP_RECEIVER_FAULT

static final javax.xml.namespace.QName SOAP_RECEIVER_FAULT

SOAP 1.2 Receiver Fault

Since:

SAAJ 1.3

java.lang.Object
  javax.xml.transform.dom.DOMResult
      javax.xml.soap.SAAJResult

public SAAJResult()
           throws SOAPException

public SAAJResult(java.lang.String protocol)
           throws SOAPException

public SAAJResult(SOAPMessage message)

public SAAJResult(SOAPElement rootNode)

public Node getResult()

---

Rationale : Acts as a holder for the results of a JAXP transformation or a JAXB marshalling, in the form of a SAAJ tree. Introduction of this class provides ease of use for the SAAJ developer since he need not  deal with the usual DOM results.

---

Method Detail

addDetailEntry

DetailEntry addDetailEntry(javax.xml.namespace.QName qname)
                           throws SOAPException

Creates a new DetailEntry object with the given QName and adds it to this Detail object. This method is the preferred over the one using Name.

Parameters:

qname - a QName object identifying the new DetailEntry object

Throws:

SOAPException - thrown when there is a problem in adding a DetailEntry object to this Detail object.

Since:

SAAJ 1.3

See Also:

addDetailEntry(Name name)

addFault

SOAPFault addFault(javax.xml.namespace.QName faultCode,
                   java.lang.String faultString,
                   java.util.Locale locale)
                   throws SOAPException

Creates a new SOAPFault object and adds it to this SOAPBody object. The type of the SOAPFault will be a SOAP 1.1 or a SOAP 1.2 SOAPFault depending on the protocol specified while creating the MessageFactory instance.

For SOAP 1.2 the faultCode parameter is the value of the Fault/Code/Value element and the faultString parameter is the value of the Fault/Reason element. For SOAP 1.1 the faultCode parameter is the value of the faultcode element and the faultString parameter is the value of the faultstring element.

A SOAPBody may contain at most one SOAPFault child element.

Parameters:

faultCode - a QName object giving the fault code to be set; must be one of the fault codes defined in a SOAP specification and of type QName

faultString - a String giving an explanation of the fault

locale - a Locale object indicating the native language of the faultString

Returns:

the new SOAPFault object

Throws:

SOAPException - if there is a SOAP error

Since:

SAAJ 1.3

See Also:

SOAPFault.setFaultCode(javax.xml.soap.Name), SOAPFault.setFaultString(java.lang.String), addFault(Name faultCode, String faultString, Locale locale)

addFault

SOAPFault addFault(javax.xml.namespace.QName faultCode,
                   java.lang.String faultString)
                   throws SOAPException

Creates a new SOAPFault object and adds it to this SOAPBody object. The type of the SOAPFault will be a SOAP 1.1 or a SOAP 1.2 SOAPFault depending on the protocol specified while creating the MessageFactory instance.

For SOAP 1.2 the faultCode parameter is the value of the Fault/Code/Value element and the faultString parameter is the value of the Fault/Reason/Text element. For SOAP 1.1 the faultCode parameter is the value of the faultcode element and the faultString parameter is the value of the faultstring element.

In case of a SOAP 1.2 fault, the default value for the mandatory xml:lang attribute on the Fault/Reason/Text element will be set to java.util.Locale.getDefault()

A SOAPBody may contain at most one SOAPFault child element

Parameters:

faultCode - a QName object giving the fault code to be set; must be one of the fault codes defined in a SOAP specification and of type QName

faultString - a String giving an explanation of the fault

Returns:

the new SOAPFault object

Throws:

SOAPException - if there is a SOAP error

Since:

SAAJ 1.3

See Also:

SOAPFault.setFaultCode(javax.xml.soap.Name), SOAPFault.setFaultString(java.lang.String), addFault(Name faultCode, String faultString)

addBodyElement

SOAPBodyElement addBodyElement(javax.xml.namespace.QName qname)
                               throws SOAPException

Creates a new SOAPBodyElement object with the specified QName and adds it to this SOAPBody object.

Parameters:

qname - a QName object with the qname for the new SOAPBodyElement object

Returns:

the new SOAPBodyElement object

Throws:

SOAPException - if a SOAP error occurs

Since:

SAAJ 1.3

See Also:

addBodyElement(Name)

addChildElement

public SOAPElement addChildElement(javax.xml.namespace.QName qname)
                            throws SOAPException

Creates a new SOAPElement object initialized with the given QName object and adds the new element to this SOAPElement object. The namespace, localname and prefix of the new SOAPElement are all taken from the qname argument.

Parameters:

qname - a QName object with the XML name for the new element

Returns:

the new SOAPElement object that was created

Throws:

SOAPException - if there is an error in creating the SOAPElement object

Since:

SAAJ 1.3

See Also:

addChildElement(Name)

addAttribute

SOAPElement addAttribute(javax.xml.namespace.QName qname,
                         java.lang.String value)
                         throws SOAPException

Adds an attribute with the specified name and value to this SOAPElement object.

Parameters:

qname - a QName object with the name of the attribute

value - a String giving the value of the attribute

Returns:

the SOAPElement object into which the attribute was inserted

Throws:

SOAPException - if there is an error in creating the Attribute, or it is invalid to set an attribute with QName qname on this SOAPElement.

Since:

SAAJ 1.3

See Also:

addAttribute(Name, String)

getAttributeValue

java.lang.String getAttributeValue(javax.xml.namespace.QName qname)

Returns the value of the attribute with the specified qname.

Parameters:

qname - a QName object with the qname of the attribute

Returns:

a String giving the value of the specified attribute, Null if there is no such attribute

Since:

SAAJ 1.3

See Also:

getAttributeValue(Name)

createQName

javax.xml.namespace.QName createQName(java.lang.String localName,
                                      java.lang.String prefix)
                                      throws SOAPException

Creates a QName whose namespace URI is the one associated with the parameter, prefix, in the context of this SOAPElement. The remaining elements of the new QName are taken directly from the parameters, localName and prefix.

Parameters:

localName - a String containing the local part of the name.

prefix - a String containing the prefix for the name.

Returns:

a QName with the specified localName and prefix, and with a namespace that is associated with the prefix in the context of this SOAPElement. This namespace will be the same as the one that would be returned by getNamespaceURI(String) if it were given prefix as it's parameter.

Throws:

SOAPException - if the QName cannot be created.

Since:

SAAJ 1.3

getElementQName

javax.xml.namespace.QName getElementQName()

Returns the qname of this SOAPElement object.

Returns:

a QName object with the qname of this SOAPElement object

Since:

SAAJ 1.3

See Also:

getElementName()

setElementQName

public SOAPElement setElementQName(javax.xml.namespace.QName newName)
                            throws SOAPException

Changes the name of this Element to newName if possible. SOAP Defined elements such as SOAPEnvelope, SOAPHeader, SOAPBody etc. cannot have their names changed using this method. Any attempt to do so will result in a SOAPException being thrown.

Callers should not rely on the element instance being renamed as is. Implementations could end up copying the content of the SOAPElement to a renamed instance.

Parameters:

newName - the new name for the Element.

Returns:

The renamed Node

Throws:

SOAPException - if changing the name of this Element is not allowed.

Since:

SAAJ 1.3

removeAttribute

boolean removeAttribute(javax.xml.namespace.QName qname)

Removes the attribute with the specified qname.

Parameters:

qname - the QName object with the qname of the attribute to be removed

Returns:

true if the attribute was removed successfully; false if it was not

Since:

SAAJ 1.3

See Also:

removeAttribute(Name)

getAllAttributesAsQNames

java.util.Iterator getAllAttributesAsQNames()

Returns an Iterator over all of the attributes in this SOAPElement as QName objects. The iterator can be used to get the attribute QName, which can then be passed to the method getAttributeValue to retrieve the value of each attribute.

Returns:

an iterator over the QNames of the attributes

Since:

SAAJ 1.3

See Also:

getAllAttributes()

getChildElements

java.util.Iterator getChildElements(javax.xml.namespace.QName qname)

Returns an Iterator over all the immediate child Nodes of this element with the specified qname. All of these children will be SOAPElement nodes.

Calling this method may cause child Element, SOAPElement and org.w3c.dom.Text nodes to be replaced by SOAPElement, SOAPHeaderElement, SOAPBodyElement or javax.xml.soap.Text nodes as appropriate for the type of this parent node. As a result the calling application must treat any existing references to these child nodes that have been obtained through DOM APIs as invalid and either discard them or refresh them with the values returned by this Iterator. This behavior can be avoided by calling the equivalent DOM APIs. See javax.xml.soap for more details.

Parameters:

qname - a QName object with the qname of the child elements to be returned

Returns:

an Iterator object over all the elements in this SOAPElement object with the specified qname

Since:

SAAJ 1.3

See Also:

getChildElements(Name)

javax.xml.soap
Interface SOAPFault

All Superinterfaces:

org.w3c.dom.Element, org.w3c.dom.Node, SOAPBodyElement, SOAPElement

getFaultCodeAsQName

javax.xml.namespace.QName getFaultCodeAsQName()

Gets the fault code for this SOAPFault object as a QName object.

Returns:

a QName representing the faultcode

Since:

SAAJ 1.3

See Also:

setFaultCode(QName)

setFaultCode

void setFaultCode(javax.xml.namespace.QName faultCodeQName)
                  throws SOAPException

Sets this SOAPFault object with the given fault code. It is preferable to use this method over setFaultCode(Name).

Parameters:

faultCodeQName - a QName object giving the fault code to be set. It must be namespace qualified.

Throws:

SOAPException - if there was an error in adding the faultcode element to the underlying XML tree.

Since:

SAAJ 1.3

See Also:

getFaultCodeAsQName(), setFaultCode(Name), getFaultCodeAsQName()

createElement

Creates a SOAPElement object initialized with the given QName object. The concrete type of the return value will depend on the name given to the new SOAPElement. For instance, a new SOAPElement with the name "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a SOAPEnvelope that supports SOAP 1.2 behavior to be created.

Parameters:

qname - a QName object with the XML name for the new element

Returns:

the new SOAPElement object that was created

Throws:

SOAPException - if there is an error in creating the SOAPElement object

Since:

SAAJ 1.3

See Also:

createElement(Name)

javax.xml.soap
Interface SOAPHeader

All Superinterfaces:

org.w3c.dom.Element, org.w3c.dom.Node, SOAPElement

addHeaderElement

SOAPHeaderElement addHeaderElement(javax.xml.namespace.QName qname)
                                   throws SOAPException

Creates a new SOAPHeaderElement object initialized with the specified qname and adds it to this SOAPHeader object.

Parameters:

qname - a QName object with the qname of the new SOAPHeaderElement object

Returns:

the new SOAPHeaderElement object that was inserted into this SOAPHeader object

Throws:

SOAPException - if a SOAP error occurs

Since:

SAAJ 1.3

See Also:

addHeaderElement(Name)

javax.xml.soap
Class MessageFactory

java.lang.Object
  javax.xml.soap.MessageFactory

public abstract class MessageFactory
extends java.lang.Object

A factory for creating SOAPMessage objects.

A SAAJ client can create a MessageFactory object using the method newInstance, as shown in the following lines of code.

       MessageFactory mf = MessageFactory.newInstance();
       MessageFactory mf12 = MessageFactory.newInstance(SOAPConstants.SOAP_1_2_PROTOCOL);
 

All MessageFactory objects, regardless of how they are created, will produce SOAPMessage objects that have the following elements by default:

• A SOAPPart object
• A SOAPEnvelope object
• A SOAPBody object
• A SOAPHeader object

• createMessage() -- message has no content
  This is the method clients would normally use to create a request message.
• createMessage(MimeHeaders, java.io.InputStream) -- message has content from the InputStream object and headers from the MimeHeaders object
  This method can be used internally by a service implementation to create a message that is a response to a request.

newInstance

public static MessageFactory newInstance()
                                  throws SOAPException

Creates a new MessageFactory object that is an instance of the default implementation (SOAP 1.1), This method uses the following ordered lookup procedure to determine the MessageFactory implementation class to load:

• Use the javax.xml.soap.MessageFactory system property.
• Use the properties file "lib/jaxm.properties" in the JRE directory. This configuration file is in standard java.util.Properties format and contains the fully qualified name of the implementation class with the key being the system property defined above.
• Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API will look for a classname in the file META-INF/services/javax.xml.soap.MessageFactory in jars available to the runtime.
• Use the SAAJMetaFactory instance to locate the MessageFactory implementation class.

Returns:

a new instance of a MessageFactory

Throws:

SOAPException - if there was an error in creating the default implementation of the MessageFactory.

See Also:

SAAJMetaFactory

createMessage

public abstract SOAPMessage createMessage()
                                   throws SOAPException

Creates a new SOAPMessage object with the default SOAPPart, SOAPEnvelope, SOAPBody, and SOAPHeader objects. Profile-specific message factories can choose to prepopulate the SOAPMessage object with profile-specific headers.

Content can be added to this message's SOAPPart object, and the message can be sent "as is" when a message containing only a SOAP part is sufficient. Otherwise, the SOAPMessage object needs to create one or more AttachmentPart objects and add them to itself. Any content that is not in XML format must be in an AttachmentPart object.

Returns:

a new SOAPMessage object

Throws:

SOAPException - if a SOAP error occurs

java.lang.UnsupportedOperationException - if the protocol of this MessageFactory instance is DYNAMIC_SOAP_PROTOCOL.

createMessage

public abstract SOAPMessage createMessage(MimeHeaders headers,
                                          java.io.InputStream in)
                                   throws java.io.IOException,
                                          SOAPException

Internalizes the contents of the given InputStream object into a new SOAPMessage object and returns the SOAPMessage object.

Parameters:

in - the InputStream object that contains the data for a message

headers - the transport-specific headers passed to the message in a transport-independent fashion for creation of the message

Returns:

a new SOAPMessage object containing the data from the given InputStream object

Throws:

java.io.IOException - if there is a problem in reading data from the input stream

SOAPException - may be thrown if the message is invalid

java.lang.IllegalArgumentException - if the MessageFactory requires one or more MIME headers to be present in the headers parameter and they are missing. MessageFactory implementations for SOAP_1_1_PROTOCOL or SOAP_1_2_PROTOCOL must not throw IllegalArgumentException for this reason.

java.lang.UnsupportedOperationException - if the protocol specified for the SOAPFactory was DYNAMIC_SOAP_PROTOCOL

javax.xml.soap
Interface SOAPFault

public interface SOAPFault
extends SOAPBodyElement

An element in the SOAPBody object that contains error and/or status information. This information may relate to errors in the SOAPMessage object or to problems that are not related to the content in the message itself. Problems not related to the message itself are generally errors in processing, such as the inability to communicate with an upstream server.

The SOAPFault interface provides methods for retrieving the information contained in a SOAPFault object and for setting the fault code, the fault actor, and a string describing the fault. A fault code is one of the codes defined in the SOAP 1.1 specification that describe the fault. An actor is an intermediate recipient to whom a message was routed. The message path may include one or more actors, or, if no actors are specified, the message goes only to the default actor, which is the final intended recipient.  Depending on the protocol specified while creating the MessageFactory instance, a SOAPFault has sub-elements as defined in the SOAP 1.1/SOAP 1.2 specification.

getFaultString

public java.lang.String getFaultString()

Gets the fault string for this SOAPFault object.

If this SOAPFault is part of a message that supports SOAP 1.2 then this call is equivalent to:

    String reason = null;
    try {
       reason = (String) getFaultReasonTexts().next();
    } catch (SOAPException e) {}
    return reason;
 

Returns:

a String giving an explanation of the fault

See Also:

setFaultString(String), setFaultString(String, Locale)

getFaultActor

java.lang.String getFaultActor()

Gets the fault actor for this SOAPFault object.

If this SOAPFault supports SOAP 1.2 then this call is equivalent to getFaultRole()

Returns:

a String giving the actor in the message path that caused this SOAPFault object

See Also:

setFaultActor(java.lang.String)

setFaultActor

void setFaultActor(java.lang.String faultActor) throws SOAPException

Sets this SOAPFault object with the given fault actor.

The fault actor is the recipient in the message path who caused the fault to happen.

If this SOAPFault supports SOAP 1.2 then this call is equivalent to setFaultRole(String)

Parameters:

faultActor - a String identifying the actor that caused this SOAPFault object

Throws:

SOAPException - if there was an error in adding the faultActor to the underlying XML tree.

See Also:

getFaultActor()

getDetail

Detail getDetail()

Returns the optional detail element for this SOAPFault object.

A Detail object carries application-specific error information related to SOAPBodyElement objects, the scope of the error information is restricted to faults in the SOAPBodyElement objects if this is a SOAP 1.1 Fault.

Returns:

a Detail object with application-specific error information if present, null otherwise.

setFaultString

void setFaultString(java.lang.String faultString)
                    throws SOAPException

Sets the fault string for this SOAPFault object to the given string.

If this SOAPFault is part of a message that supports SOAP 1.2 then this call is equivalent to:

      addFaultReasonText(faultString, Locale.getDefault());
 

Parameters:

faultString - a String giving an explanation of the fault

Throws:

SOAPException - if there was an error in adding the faultString to the underlying XML tree.

See Also:

getFaultString()

setFaultString

void setFaultString(java.lang.String faultString,
                    java.util.Locale locale)
                    throws SOAPException

Sets the fault string for this SOAPFault object to the given string and localized to the given locale.

If this SOAPFault is part of a message that supports SOAP 1.2 then this call is equivalent to:

      addFaultReasonText(faultString, locale);
 

Parameters:

faultString - a String giving an explanation of the fault

locale - a Locale object indicating the native language of the faultString

Throws:

SOAPException - if there was an error in adding the faultString to the underlying XML tree.

Since:

SAAJ 1.2

See Also:

getFaultString()

getFaultStringLocale

public java.util.Locale getFaultStringLocale()

Gets the locale of the fault string for this SOAPFault object.

If this SOAPFault is part of a message that supports SOAP 1.2 then this call is equivalent to:

    Locale locale = null;
    try {
        locale = (Locale) getFaultReasonLocales().next();
    } catch (SOAPException e) {}
    return locale;
 

Returns:

a Locale object indicating the native language of the fault string or null if no locale was specified

Since:

SAAJ 1.2

See Also:

setFaultString(String, Locale)

addAttribute

SOAPElement addAttribute(Name name,
                         java.lang.String value)
                         throws SOAPException

Adds an attribute with the specified name and value to this SOAPElement object.

Parameters:

name - a Name object with the name of the attribute

value - a String giving the value of the attribute

Returns:

the SOAPElement object into which the attribute was inserted

Throws:

SOAPException - if there is an error in creating the Attribute, or it is invalid to set an attribute with Name name on this SOAPElement.

See Also:

addAttribute(javax.xml.namespace.QName, String)

addChildElement

SOAPElement addChildElement(Name name)
                            throws SOAPException

This method may be deprecated in a future release of SAAJ in favor of addChildElement(javax.xml.namespace.QName)

Parameters:

name - a Name object with the XML name for the new element

Returns:

the new SOAPElement object that was created

Throws:

SOAPException - if there is an error in creating the SOAPElement object

See Also:

addChildElement(javax.xml.namespace.QName)

addChildElement

SOAPElement addChildElement(java.lang.String localName)
                            throws SOAPException

Creates a new SOAPElement object initialized with the specified local name and adds the new element to this SOAPElement object.  The new  SOAPElement  inherits any in-scope default namespace.

Parameters:

localName - a String giving the local name for the element

Returns:

the new SOAPElement object that was created

Throws:

SOAPException - if there is an error in creating the SOAPElement object

addChildElement

SOAPElement addChildElement(java.lang.String localName,
                            java.lang.String prefix)
                            throws SOAPException

Creates a new SOAPElement object initialized with the specified local name and prefix and adds the new element to this SOAPElement object. 

Parameters:

localName - a String giving the local name for the new element

prefix - a String giving the namespace prefix for the new element

Returns:

the new SOAPElement object that was created

Throws:

SOAPException -  If the prefix is not valid in the context of this  SOAPElement or  if there is an error in creating the SOAPElelement object.

addChildElement

public SOAPElement addChildElement(SOAPElement element)
                            throws SOAPException

Add a SOAPElement as a child of this SOAPElement instance. The SOAPElement is expected to be created by a SOAPElementFactory. Callers should not rely on the element instance being added as is into the XML tree. Implementations could end up copying the content of the SOAPElement passed into an instance of a different SOAPElement implementation. For instance if addChildElement() is called on a SOAPHeader, element will be copied into an instance of a SOAPHeaderElement.

The fragment rooted in element is either added as a whole or not at all, if there was an error.

The fragment rooted in element cannot contain elements named "Envelope", "Header" or "Body" and in the SOAP namespace. Any namespace prefixes present in the fragment should be fully resolved using appropriate namespace declarations within the fragment itself.

Parameters:

element - the SOAPElement to be added as a new child

Returns:

an instance representing the new SOAP element that was actually added to the tree.

Throws:

SOAPException - if there was an error in adding this element as a child

javax.xml.soap
Interface Name

public interface Name

A representation of an XML name. This interface provides methods for getting the local and namespace-qualified names and also for getting the prefix associated with the namespace for the name. It is also possible to get the URI of the namespace.

The following is an example of a namespace declaration in an element.

   <wombat:GetLastTradePrice xmlns:wombat="http://www.wombat.org/trader">
 

• getQualifiedName will return "prefix:LocalName" = "WOMBAT:GetLastTradePrice"
• getURI will return "http://www.wombat.org/trader"
• getLocalName will return "GetLastTracePrice"
• getPrefix will return "WOMBAT"

XML namespaces are used to disambiguate SOAP identifiers from application-specific identifiers.

Name objects are created using the method SOAPEnvelope.createName, which has two versions. One method creates Name objects with a local name, a namespace prefix, and a namespace URI. and the second creates Name objects with just a local name. The following line of code, in which se is a SOAPEnvelope object, creates a new Name object with all three.

     Name name = se.createName("GetLastTradePrice", "WOMBAT",
                                "http://www.wombat.org/trader");
 

     element.addChildElement(name);
 

The Name interface may be deprecated in a future release of SAAJ in favor of javax.xml.namespace.QName

See Also:

SOAPEnvelope.createName, SOAPFactory.createName

javax.xml.soap
Interface SOAPHeader

All Superinterfaces:

org.w3c.dom.Element, org.w3c.dom.Node, SOAPElement

examineMustUnderstandHeaderElements

java.util.Iterator examineMustUnderstandHeaderElements(java.lang.String actor)

Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object that have the specified actor and that have a MustUnderstand attribute whose value is equivalent to true.

In SOAP 1.2 the env:actor attribute is replaced by the env:role attribute, but with essentially the same semantics.

Parameters:

actor - a String giving the URI of the actor/role for which to search

Returns:

an Iterator object over all the SOAPHeaderElement objects that contain the specified actor / role and are marked as MustUnderstand

Since:

SAAJ 1.2

See Also:

examineHeaderElements(java.lang.String), extractHeaderElements(java.lang.String), SOAPConstants.URI_SOAP_ACTOR_NEXT

examineHeaderElements

java.util.Iterator examineHeaderElements(java.lang.String actor)

Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object that have the specified actor. An actor is a global attribute that indicates the intermediate parties that should process a message before it reaches its ultimate receiver. An actor receives the message and processes it before sending it on to the next actor. The default actor is the ultimate intended recipient for the message, so if no actor attribute is included in a SOAPHeader object, it is sent to the ultimate receiver along with the message body.

In SOAP 1.2 the env:actor attribute is replaced by the env:role attribute, but with essentially the same semantics.

Parameters:

actor - a String giving the URI of the actor/role for which to search

Returns:

an Iterator object over all the SOAPHeaderElement objects that contain the specified actor/role

See Also:

extractHeaderElements(java.lang.String), SOAPConstants.URI_SOAP_ACTOR_NEXT

extractHeaderElements

java.util.Iterator extractHeaderElements(java.lang.String actor)

Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object that have the specified actor and detaches them from this SOAPHeader object.

This method allows an actor to process the parts of the SOAPHeader object that apply to it and to remove them before passing the message on to the next actor.

In SOAP 1.2 the env:actor attribute is replaced by the env:role attribute, but with essentially the same semantics.

Parameters:

actor - a String giving the URI of the actor/role for which to search

Returns:

an Iterator object over all the SOAPHeaderElement objects that contain the specified actor/role

See Also:

examineHeaderElements(java.lang.String), SOAPConstants.URI_SOAP_ACTOR_NEXT

createAttachmentPart

public AttachmentPart createAttachmentPart(java.lang.Object content,
                                           java.lang.String contentType)

Creates an AttachmentPart object and populates it with the specified data of the specified content type. The type of the Object should correspond to the value given for the Content-Type.

Parameters:

content - an Object containing the content for this SOAPMessage  the AttachmentPart object  to be created

contentType - a String object giving the type of content; examples are "text/xml", "text/plain", and "image/jpeg"

Returns:

a new AttachmentPart object that contains the given data

Throws:

java.lang.IllegalArgumentException - may be thrown if the contentType does not match the type of the content object, or if there was no DataContentHandler object for the given content object

See Also:

DataHandler, DataContentHandler

javax.xml.soap
Class AttachmentPart

java.lang.Object
  javax.xml.soap.AttachmentPart

setContent

public abstract void setContent(java.lang.Object object,
                                java.lang.String contentType)

Sets the content of this attachment part to that of the given Object and sets the value of the Content-Type header to the given type. The type of the Object should correspond to the value given for the Content-Type. This depends on the particular set of DataContentHandler objects in use.

Parameters:

object - the Java object that makes up the content for this attachment part

contentType - the MIME string that specifies the type of the content

Throws:

java.lang.IllegalArgumentException - may be thrown if the contentType does not match the type of the content object, or if there was no DataContentHandler object for this content object

See Also:

getContent()

javax.xml.soap
Class SOAPMessage

java.lang.Object
  javax.xml.soap.SOAPMessage

 

Method Summary
abstract  AttachmentPart	getAttachment(SOAPElement element)           Returns an AttachmentPart object that is associated with an attachment that is referenced by this SOAPElement or null if no such attachment exists.
abstract  void	removeAttachments(MimeHeaders headers)           Removes all the AttachmentPart objects that have header entries that match the specified headers.

Method Detail

getAttachment

public abstract AttachmentPart getAttachment(SOAPElement element)
                                      throws SOAPException

Returns an AttachmentPart object that is associated with an attachment that is referenced by this SOAPElement or null if no such attachment exists. References can be made via an href attribute as described in SOAP Messages with Attachments, or via a single Text child node containing a URI as described in the WS-I Attachments Profile 1.0 for elements of schema type ref:swaRef. These two mechanisms must be supported. The support for references via href attribute also implies that this method should also be supported on an element that is an xop:Include element ( XOP). other reference mechanisms may be supported by individual implementations of this standard. Contact your vendor for details.

Parameters:

element - The SOAPElement containing the reference to an Attachment

Returns:

the referenced AttachmentPart or null if no such AttachmentPart exists or no reference can be found in this SOAPElement.

Throws:

SOAPException - if there is an error in the attempt to access the attachment

Since:

SAAJ 1.3

---

Rationale : see javadoc explanation above.

---

removeAttachments

public abstract void removeAttachments(MimeHeaders headers)

Removes all the AttachmentPart objects that have header entries that match the specified headers. Note that the removed attachment could have headers in addition to those specified.

Parameters:

headers - a MimeHeaders object containing the MIME headers for which to search

Since:

SAAJ 1.3

---

Rationale : There was no API in SAAJ 1.2  to remove a particular Attachment

---

createElement

public SOAPElement createElement(org.w3c.dom.Element domElement)throws SOAPException

Creates a SOAPElement object from an existing DOM Element. If the DOM Element that is passed in as an argument is already a SOAPElement then this method must return it unmodified without any further work. Otherwise, a new SOAPElement is created and a deep copy is made of the domElement argument. The concrete type of the return value will depend on the name of the domElement argument. If any part of the tree rooted in domElement violates SOAP rules, a SOAPException will be thrown.

Parameters:

domElement - - the Element to be copied.

Returns:

a new SOAPElement that is a copy of domElement.

Throws:

SOAPException - if there is an error in creating the SOAPElement object

Since:

SAAJ 1.3

javax.xml.soap
Interface SOAPBody

All Superinterfaces:

org.w3c.dom.Element, org.w3c.dom.Node, SOAPElement

 

extractContentAsDocument

org.w3c.dom.Document extractContentAsDocument()throws SOAPException

Creates a new DOM Document and sets the first child of this SOAPBody as it's document element. The child SOAPElement is removed as part of the process.

Returns:

the Document representation of the SOAPBody content.

Throws:

SOAPException - if there is not exactly one child SOAPElement of the SOAPBody.

Since:

SAAJ 1.3

get

public SOAPMessage get(java.lang.Object to)
                throws SOAPException

Parameters:

to - an Object that identifies where the request should be sent. Objects of type java.lang.String and java.net.URL must be supported.

Returns:

the SOAPMessage object that is the response to the get message request

Throws:

SOAPException - if there is a SOAP error

Since:

SAAJ 1.3