## javax.xml.soap
Interface SOAPHeader

All Superinterfaces:
  org.w3c.dom.Element, Node, org.w3c.dom.Node, SOAPElement

All Known Implementing Classes:
  SOAPHeader

public interface SOAPHeader
extends SOAPElement

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);

See Also:
  `SOAPHeaderElement`

Field Summary

Fields inherited from interface org.w3c.dom.Node
`ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE`

Method Summary
`SOAPHeaderElement` `addHeaderElement(Name name)` Creates a new `SOAPHeaderElement` object initialized with the specified name and adds it to this `SOAPHeader` object.
`java.util.Iterator` `examineAllHeaderElements()` Returns an `Iterator` over all the `SOAPHeaderElement` objects in this `SOAPHeader` object.
`java.util.Iterator` `examineHeaderElements(java.lang.String actor)` Returns a list of all the `SOAPHeaderElement` objects in this `SOAPHeader` object that have the the specified actor.
`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`.
`java.util.Iterator` `extractAllHeaderElements()` Returns an `Iterator` over all the `SOAPHeaderElement` objects in this `SOAPHeader` object and detaches them from this `SOAPHeader` object.
`java.util.Iterator` `extractHeaderElements(java.lang.String actor)` Returns a list of all the `SOAPHeaderElement` objects in this `SOAPHeader` object that have the the specified actor and detaches them from this `SOAPHeader` object.

Methods inherited from interface javax.xml.soap.SOAPElement
`addAttribute, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addNamespaceDeclaration, addTextNode, getAllAttributes, getAttributeValue, getChildElements, getChildElements, getElementName, getEncodingStyle, getNamespacePrefixes, getNamespaceURI, getVisibleNamespacePrefixes, removeAttribute, removeContents, removeNamespaceDeclaration, setEncodingStyle`

Methods inherited from interface javax.xml.soap.Node
`detachNode, getParentElement, getValue, recycleNode, setParentElement, setValue`

Methods inherited from interface org.w3c.dom.Node
`appendChild, cloneNode, getAttributes, getChildNodes, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, hasAttributes, hasChildNodes, insertBefore, isSupported, normalize, removeChild, replaceChild, setNodeValue, setPrefix`

Methods inherited from interface org.w3c.dom.Element
`getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS`

Method Detail

### addHeaderElement

    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` - a `Name` object with the name of the new `SOAPHeaderElement` object
  Returns:
    the new `SOAPHeaderElement` object that was inserted into this `SOAPHeader` object
  Throws:
    `SOAPException` - if a SOAP error occurs

### examineHeaderElements

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

  Returns a list of all the `SOAPHeaderElement` objects in this `SOAPHeader` object that have the the specified actor. An actor is a global attribute that indicates the intermediate parties to whom the message should be sent. An actor receives the message and then sends it 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, the message is sent to its ultimate destination.

  Parameters:
    `actor` - a `String` giving the URI of the actor for which to search
  Returns:
    an `Iterator` object over all the `SOAPHeaderElement` objects that contain the specified actor
  See Also:
    `extractHeaderElements(java.lang.String)`

### extractHeaderElements

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

  Returns a list of all the `SOAPHeaderElement` objects in this `SOAPHeader` object that have the the specified actor and detaches them from this `SOAPHeader` object.

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

  Parameters:
    `actor` - a `String` giving the URI of the actor for which to search
  Returns:
    an `Iterator` object over all the `SOAPHeaderElement` objects that contain the specified actor
  See Also:
    `examineHeaderElements(java.lang.String)`

### examineMustUnderstandHeaderElements

    public 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`.

  Parameters:
    `actor` - a `String` giving the URI of the actor for which to search
  Returns:
    an `Iterator` object over all the `SOAPHeaderElement` objects that contain the specified actor and are marked as MustUnderstand

### examineAllHeaderElements

    public java.util.Iterator examineAllHeaderElements()

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

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

### extractAllHeaderElements

    public java.util.Iterator extractAllHeaderElements()

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

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

Copyright © 2005 Apache Web Services Project. All Rights Reserved.