public interface SOAPHeader extends SOAPElement {
// Public Instance Methods
    public abstract SOAPHeaderElement addHeaderElement Name name) 
        throws SOAPException; 
    public abstract Iterator examineHeaderElements(String actor); 
    public abstract Iterator extractHeaderElements(String actor); 
}

SOAPHeader is a subinterface of SOAPElement that acts as a container for SOAP message headers. A single SOAPHeader element is always found as the first element of the SOAPEnvelope within a SOAPMessage returned by the default MessageFactory provided by the SAAJ reference implementation. However, since the use of headers is optional, if it is not required, it may be removed by calling its detachNode( ) method:

SOAPMessage msg = factory.createMessage;
SOAPPart part = msg.getSOAPPart;
SOAPHeader header = part.getEnvelope.getHeader;
header.detachNode;

A SOAPHeader may contain any number of SOAP headers, which are represented by SOAPHeaderElements. The most direct way to add a header is to use the addHeaderElement( ) method, which requires a Name object as its argument. Other elements may be nested within the SOAPHeaderElement as required. The following code adds the header code BookHeader to a SOAP message:

SOAPHeader header = part.getEnvelope.getHeader;
SOAPHeaderElement e = header.addHeaderElement(
     factory.createName("BookHeader", "book", "urn:BookService"));

Alternatively, the addChildElement( ) methods that SOAPHeader inherits from SOAPElement can be used to achieve the same result. The following code extract is equivalent to that shown previously, and also results in the creation of a SOAPHeaderElement:

SOAPHeader header = part.getEnvelope.getHeader;
SOAPElement e = header.addChildElement(factory.createName("BookHeader", 
                                          "book", "urn:BookService"));

Elements created using SOAPFactory or SOAPElementFactory that are added to a SOAPHeader using the addChildElement( ) method are copied and converted to instances of SOAPHeaderElement before being included in the header.

The extractHeaderElements( ) method returns an Iterator over the set of nested SOAPHeaderElements for which the actor attribute matches the supplied argument and removes those elements from the header. By default, a SOAPHeaderElement is created with an actor attribute that indicates that it should be processed by the next system that receives it. The following code extract therefore retrieves all headers intended for the system that has received the message, which is assumed to be identified by the URI urn:thisSystem:

Iterator iter1 = header.extractHeaderElements(
     SOAPConstants.URI_SOAP_ACTOR_NEXT);
Iterator iter2 = header.extractHeaderElements("urn:thisSystem");

Removal of header elements intended for the system that is processing a message is required by the SOAP specification. However, if you just want to look at the headers with a given actor URI without removing them, use the examineHeaderElements( ) method instead.

Returned By

SOAPEnvelope.{addHeader( ), getHeader( )}