Top Description Methods
jakarta.xml.soap

public Interface SOAPHeader

extends SOAPElement
Imports
java.util.Iterator, javax.xml.namespace.QName
A representation of the SOAP header element. A SOAP header element consists of XML data that affects the way the application-specific content is processed by the message provider. For example, transaction semantics, authentication information, and so on, can be specified as the content of a SOAPHeader object.

A SOAPEnvelope object contains an empty SOAPHeader object by default. If the SOAPHeader object, which is optional, is not needed, it can be retrieved and deleted with the following line of code. The variable se is a SOAPEnvelope object. 

se.getHeader().detachNode();
A SOAPHeader object is created with the SOAPEnvelope method addHeader. This method, which creates a new header and adds it to the envelope, may be called only after the existing header has been removed. 
se.getHeader().detachNode();
     SOAPHeader sh = se.addHeader();

A SOAPHeader object can have only SOAPHeaderElement objects as its immediate children. The method addHeaderElement creates a new HeaderElement object and adds it to the SOAPHeader object. In the following line of code, the argument to the method addHeaderElement is a Name object that is the name for the new HeaderElement object. 

SOAPHeaderElement shElement = sh.addHeaderElement(name);
Since
1.6
See Also
SOAPHeaderElement

Method Summary

Modifier and TypeMethod and Description
public SOAPHeaderElement

Returns:

the new SOAPHeaderElement object that was inserted into this SOAPHeader object
addHeaderElement(Name
a Name object with the name of the new SOAPHeaderElement object
name)

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

public SOAPHeaderElement

Returns:

the new SOAPHeaderElement object that was inserted into this SOAPHeader object
addHeaderElement(QName
a QName object with the qname of the new SOAPHeaderElement object
qname)

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

public SOAPHeaderElement

Returns:

the new SOAPHeaderElement object that was inserted into this SOAPHeader object
addNotUnderstoodHeaderElement(QName
a QName object with the name of the SOAPHeaderElement object that was not understood.
name)

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

public SOAPHeaderElement

Returns:

the new SOAPHeaderElement object that was inserted into this SOAPHeader object
addUpgradeHeaderElement(Iterator<String>
an Iterator object with the URIs of SOAP versions supported.
supportedSOAPURIs)

Creates a new Upgrade SOAPHeaderElement object initialized with the specified List of supported SOAP URIs and adds it to this SOAPHeader object.

public SOAPHeaderElement

Returns:

the new SOAPHeaderElement object that was inserted into this SOAPHeader object
addUpgradeHeaderElement(String[]
an array of the URIs of SOAP versions supported.
supportedSoapUris)

Creates a new Upgrade SOAPHeaderElement object initialized with the specified array of supported SOAP URIs and adds it to this SOAPHeader object.

public SOAPHeaderElement

Returns:

the new SOAPHeaderElement object that was inserted into this SOAPHeader object
addUpgradeHeaderElement(String
the URI of SOAP the version that is supported.
supportedSoapUri)

Creates a new Upgrade SOAPHeaderElement object initialized with the specified supported SOAP URI and adds it to this SOAPHeader object.

public Iterator<SOAPHeaderElement>

Returns:

an Iterator object over all the SOAPHeaderElement objects contained by this SOAPHeader
examineAllHeaderElements()

Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object.

public Iterator<SOAPHeaderElement>

Returns:

an Iterator object over all the SOAPHeaderElement objects that contain the specified actor / role
examineHeaderElements(String
a String giving the URI of the actor / role for which to search
actor)

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

public Iterator<SOAPHeaderElement>

Returns:

an Iterator object over all the SOAPHeaderElement objects that contain the specified actor / role and are marked as MustUnderstand
examineMustUnderstandHeaderElements(String
a String giving the URI of the actor / role for which to search
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.

public Iterator<SOAPHeaderElement>

Returns:

an Iterator object over all the SOAPHeaderElement objects contained by this SOAPHeader
extractAllHeaderElements()

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

public Iterator<SOAPHeaderElement>

Returns:

an Iterator object over all the SOAPHeaderElement objects that contain the specified actor / role
extractHeaderElements(String
a String giving the URI of the actor / role for which to search
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.

Inherited from jakarta.xml.soap.SOAPElement:
addAttributeaddAttributeaddChildElementaddChildElementaddChildElementaddChildElementaddChildElementaddChildElementaddNamespaceDeclarationaddTextNodecreateQNamegetAllAttributesgetAllAttributesAsQNamesgetAttributeValuegetAttributeValuegetChildElementsgetChildElementsgetChildElementsgetElementNamegetElementQNamegetEncodingStylegetNamespacePrefixesgetNamespaceURIgetVisibleNamespacePrefixesremoveAttributeremoveAttributeremoveContentsremoveNamespaceDeclarationsetElementQNamesetEncodingStyle

Method Detail

addHeaderElementback to summary
public SOAPHeaderElement addHeaderElement(Name name) throws SOAPException

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

Parameters
name:Name

a Name object with the name of the new SOAPHeaderElement object

Returns:SOAPHeaderElement

the new SOAPHeaderElement object that was inserted into this SOAPHeader object

Exceptions
SOAPException:
if a SOAP error occurs
See Also
SOAPHeader#addHeaderElement(javax.xml.namespace.QName)
addHeaderElementback to summary
public SOAPHeaderElement addHeaderElement(QName qname) throws SOAPException

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

Parameters
qname:QName

a QName object with the qname of the new SOAPHeaderElement object

Returns:SOAPHeaderElement

the new SOAPHeaderElement object that was inserted into this SOAPHeader object

Exceptions
SOAPException:
if a SOAP error occurs
Since
1.6, SAAJ 1.3
See Also
SOAPHeader#addHeaderElement(Name)
addNotUnderstoodHeaderElementback to summary
public SOAPHeaderElement addNotUnderstoodHeaderElement(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:QName

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

Returns:SOAPHeaderElement

the new SOAPHeaderElement object that was inserted into this SOAPHeader object

Exceptions
SOAPException:
if a SOAP error occurs.
UnsupportedOperationException:
if this is a SOAP 1.1 Header.
Since
1.6, SAAJ 1.3
addUpgradeHeaderElementback to summary
public SOAPHeaderElement addUpgradeHeaderElement(Iterator<String> 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:Iterator<String>

an Iterator object with the URIs of SOAP versions supported.

Returns:SOAPHeaderElement

the new SOAPHeaderElement object that was inserted into this SOAPHeader object

Exceptions
SOAPException:
if a SOAP error occurs.
Since
1.6, SAAJ 1.3
addUpgradeHeaderElementback to summary
public SOAPHeaderElement addUpgradeHeaderElement(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:String[]

an array of the URIs of SOAP versions supported.

Returns:SOAPHeaderElement

the new SOAPHeaderElement object that was inserted into this SOAPHeader object

Exceptions
SOAPException:
if a SOAP error occurs.
Since
1.6, SAAJ 1.3
addUpgradeHeaderElementback to summary
public SOAPHeaderElement addUpgradeHeaderElement(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:String

the URI of SOAP the version that is supported.

Returns:SOAPHeaderElement

the new SOAPHeaderElement object that was inserted into this SOAPHeader object

Exceptions
SOAPException:
if a SOAP error occurs.
Since
1.6, SAAJ 1.3
examineAllHeaderElementsback to summary
public Iterator<SOAPHeaderElement> examineAllHeaderElements()

Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object.

Returns:Iterator<SOAPHeaderElement>

an Iterator object over all the SOAPHeaderElement objects contained by this SOAPHeader

Since
1.6, SAAJ 1.2
See Also
extractAllHeaderElements
examineHeaderElementsback to summary
public Iterator<SOAPHeaderElement> examineHeaderElements(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:String

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

Returns:Iterator<SOAPHeaderElement>

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

See Also
extractHeaderElements, SOAPConstants#URI_SOAP_ACTOR_NEXT
examineMustUnderstandHeaderElementsback to summary
public Iterator<SOAPHeaderElement> examineMustUnderstandHeaderElements(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:String

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

Returns:Iterator<SOAPHeaderElement>

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

Since
1.6, SAAJ 1.2
See Also
examineHeaderElements, extractHeaderElements, SOAPConstants#URI_SOAP_ACTOR_NEXT
extractAllHeaderElementsback to summary
public Iterator<SOAPHeaderElement> extractAllHeaderElements()

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

Returns:Iterator<SOAPHeaderElement>

an Iterator object over all the SOAPHeaderElement objects contained by this SOAPHeader

Since
1.6, SAAJ 1.2
See Also
examineAllHeaderElements
extractHeaderElementsback to summary
public Iterator<SOAPHeaderElement> extractHeaderElements(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:String

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

Returns:Iterator<SOAPHeaderElement>

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

See Also
examineHeaderElements, SOAPConstants#URI_SOAP_ACTOR_NEXT