SOAPHeader (Java Platform SE 8 )
Keywords: javax.xml.soap.SOAPHeader interface
Date: 2026-07-22

javax.xml.soap

## Interface SOAPHeader

- All Superinterfaces:
    Element, Node, SOAPElement

      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_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `SOAPHeaderElement` | `addHeaderElement(Name name)` Creates a new `SOAPHeaderElement` object initialized with the specified name and adds it to this `SOAPHeader` object.
    `SOAPHeaderElement` | `addHeaderElement(QName qname)` Creates a new `SOAPHeaderElement` object initialized with the specified qname and adds it to this `SOAPHeader` object.
    `SOAPHeaderElement` | `addNotUnderstoodHeaderElement(QName name)` Creates a new NotUnderstood `SOAPHeaderElement` object initialized with the specified name and adds it to this `SOAPHeader` object.
    `SOAPHeaderElement` | `addUpgradeHeaderElement(Iterator supportedSOAPURIs)` Creates a new Upgrade `SOAPHeaderElement` object initialized with the specified List of supported SOAP URIs and adds it to this `SOAPHeader` object.
    `SOAPHeaderElement` | `addUpgradeHeaderElement(String supportedSoapUri)` Creates a new Upgrade `SOAPHeaderElement` object initialized with the specified supported SOAP URI and adds it to this `SOAPHeader` object.
    `SOAPHeaderElement` | `addUpgradeHeaderElement(String[] supportedSoapUris)` Creates a new Upgrade `SOAPHeaderElement` object initialized with the specified array of supported SOAP URIs and adds it to this `SOAPHeader` object.
    `Iterator` | `examineAllHeaderElements()` Returns an `Iterator` over all the `SOAPHeaderElement` objects in this `SOAPHeader` object.
    `Iterator` | `examineHeaderElements(String actor)` Returns an `Iterator` over all the `SOAPHeaderElement` objects in this `SOAPHeader` object that have the specified actor.
    `Iterator` | `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`.
    `Iterator` | `extractAllHeaderElements()` Returns an `Iterator` over all the `SOAPHeaderElement` objects in this `SOAPHeader` object and detaches them from this `SOAPHeader` object.
    `Iterator` | `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.

    - ### Methods inherited from interface javax.xml.soap.SOAPElement

      `addAttribute, addAttribute, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addNamespaceDeclaration, addTextNode, createQName, getAllAttributes, getAllAttributesAsQNames, getAttributeValue, getAttributeValue, getChildElements, getChildElements, getChildElements, getElementName, getElementQName, getEncodingStyle, getNamespacePrefixes, getNamespaceURI, getVisibleNamespacePrefixes, removeAttribute, removeAttribute, removeContents, removeNamespaceDeclaration, setElementQName, setEncodingStyle`

    - ### Methods inherited from interface javax.xml.soap.Node

      `detachNode, getParentElement, getValue, recycleNode, setParentElement, setValue`

    - ### Methods inherited from interface org.w3c.dom.Element

      `getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, getSchemaTypeInfo, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setIdAttribute, setIdAttributeNode, setIdAttributeNS`

    - ### Methods inherited from interface org.w3c.dom.Node

      `appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData`

- - ### Method Detail

    - #### addHeaderElement

          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
      See Also:
        `addHeaderElement(javax.xml.namespace.QName)`

    - #### addHeaderElement

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

    - #### examineMustUnderstandHeaderElements

          Iterator 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` - 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

          Iterator 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` - 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

          Iterator 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` - 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`

    - #### addNotUnderstoodHeaderElement

          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` - 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.
        `UnsupportedOperationException` - if this is a SOAP 1.1 Header.
      Since:
        SAAJ 1.3

    - #### addUpgradeHeaderElement

          SOAPHeaderElement addUpgradeHeaderElement(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(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(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

    - #### examineAllHeaderElements

          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`
      Since:
        SAAJ 1.2
      See Also:
        `extractAllHeaderElements()`

    - #### extractAllHeaderElements

          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`
      Since:
        SAAJ 1.2
      See Also:
        `examineAllHeaderElements()`

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2026, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.