Package org.apache.axiom.soap

# Interface SOAPHeader

All Superinterfaces:
  `OMContainer`, `OMElement`, `OMInformationItem`, `OMNamedInformationItem`, `OMNode`, `OMSerializable`

public interface SOAPHeader extends OMElement
Interface SOAPHeader

- ## Field Summary

  ### Fields inherited from interface org.apache.axiom.om.OMNode

  `CDATA_SECTION_NODE, COMMENT_NODE, DTD_NODE, ELEMENT_NODE, ENTITY_REFERENCE_NODE, PI_NODE, SPACE_NODE, TEXT_NODE`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `SOAPHeaderBlock`
  `addHeaderBlock(String localName, OMNamespace ns)`
  Creates a new `SOAPHeaderBlock` object initialized with the specified name and adds it to this `SOAPHeader` object.
  `SOAPHeaderBlock`
  `addHeaderBlock(QName qname)`
  Creates a new `SOAPHeaderBlock` object initialized with the specified name and adds it to this `SOAPHeader` object.
  `Iterator<SOAPHeaderBlock>`
  `examineAllHeaderBlocks()`
  Returns an iterator over all the `SOAPHeaderBlock` objects in this `SOAPHeader` object.
  `Iterator<SOAPHeaderBlock>`
  `examineHeaderBlocks(String role)`
  Returns a list of all the `SOAPHeaderBlock` objects in this `SOAPHeader` object that have the the specified role.
  `Iterator<SOAPHeaderBlock>`
  `examineMustUnderstandHeaderBlocks(String role)`
  Returns an iterator over all the `SOAPHeaderBlock` objects in this `SOAPHeader` object that have the specified role and that have a `MustUnderstand` attribute whose value is equivalent to `true`.
  `Iterator<SOAPHeaderBlock>`
  `extractAllHeaderBlocks()`
  Returns an iterator over all the `SOAPHeaderBlock` objects in this `SOAPHeader` object and detaches them from this `SOAPHeader` object.
  `Iterator<SOAPHeaderBlock>`
  `extractHeaderBlocks(String role)`
  Returns a list of all the `SOAPHeaderBlock` objects in this `SOAPHeader` object that have the the specified role and detaches them from this `SOAPHeader` object.
  `Iterator<SOAPHeaderBlock>`
  `getHeaderBlocksWithName(QName name)`
  Get all header blocks with the given name.
  `Iterator<SOAPHeaderBlock>`
  `getHeaderBlocksWithNamespaceURI(String uri)`
  Get all header blocks in the given namespace.
  `ArrayList<SOAPHeaderBlock>`
  `getHeaderBlocksWithNSURI(String nsURI)`
  Deprecated.
  Use `getHeaderBlocksWithNamespaceURI(String)` instead.
  `Iterator<SOAPHeaderBlock>`
  `getHeadersToProcess(RolePlayer rolePlayer)`
  Get the appropriate set of headers for a `RolePlayer`.
  `Iterator<SOAPHeaderBlock>`
  `getHeadersToProcess(RolePlayer rolePlayer, String namespace)`
  Get the appropriate set of headers for a RolePlayer and a particular namespace.

  ### Methods inherited from interface org.apache.axiom.om.OMContainer

  `addChild, getBuilder, getChildren, getChildrenWithLocalName, getChildrenWithName, getChildrenWithNamespaceURI, getFirstChildWithName, getFirstOMChild, getSAXResult, getSAXSource, getXMLStreamReader, getXMLStreamReader, getXMLStreamReader, getXMLStreamReaderWithoutCaching, getXOPEncodedStreamReader, removeChildren, serialize, serialize, serialize, serialize, serialize, serialize, serialize, serialize, serializeAndConsume, serializeAndConsume, serializeAndConsume, serializeAndConsume`

  ### Methods inherited from interface org.apache.axiom.om.OMElement

  `addAttribute, addAttribute, cloneOMElement, declareDefaultNamespace, declareNamespace, declareNamespace, findNamespace, findNamespaceURI, getAllAttributes, getAllDeclaredNamespaces, getAttribute, getAttributeValue, getChildElements, getDefaultNamespace, getDescendants, getFirstElement, getLineNumber, getNamespaceContext, getNamespacesInScope, getText, getTextAsQName, getTextAsStream, removeAttribute, resolveQName, setLineNumber, setNamespace, setNamespaceWithNoFindInCurrentScope, setText, setText, toString, toStringWithConsume, undeclarePrefix, writeTextTo`

  ### Methods inherited from interface org.apache.axiom.om.OMInformationItem

  `clone, getOMFactory`

  ### Methods inherited from interface org.apache.axiom.om.OMNamedInformationItem

  `getLocalName, getNamespace, getNamespaceURI, getPrefix, getQName, hasName, setLocalName, setNamespace`

  ### Methods inherited from interface org.apache.axiom.om.OMNode

  `buildWithAttachments, detach, discard, getNextOMSibling, getParent, getPreviousOMSibling, getType, insertSiblingAfter, insertSiblingBefore`

  ### Methods inherited from interface org.apache.axiom.om.OMSerializable

  `build, close, isComplete, serialize, serialize, serializeAndConsume`

- ## Method Details

  - ### addHeaderBlock

    SOAPHeaderBlock addHeaderBlock(String localName, OMNamespace ns) throws OMException
    Creates a new `SOAPHeaderBlock` object initialized with the specified name and adds it to this `SOAPHeader` object.
    Parameters:
      `localName` - the local name of the header block
      `ns` - the namespace of the header block; must not be `null` and must specify a non empty namespace URI
    Returns:
      the new `SOAPHeaderBlock` object that was inserted into this `SOAPHeader` object
    Throws:
      `OMException` - if an error occurs, e.g. if no namespace was specified

  - ### addHeaderBlock

    SOAPHeaderBlock addHeaderBlock(QName qname) throws OMException
    Creates a new `SOAPHeaderBlock` object initialized with the specified name and adds it to this `SOAPHeader` object.
    Parameters:
      `qname` - the name of the header block (which must have a non empty namespace URI)
    Returns:
      the new `SOAPHeaderBlock` object that was inserted into this `SOAPHeader` object
    Throws:
      `OMException` - if an error occurs, e.g. if the namespace URI specified by the `QName` is empty

  - ### getHeadersToProcess

    Iterator<SOAPHeaderBlock> getHeadersToProcess(RolePlayer rolePlayer)
    Get the appropriate set of headers for a `RolePlayer`.

    The `RolePlayer` indicates whether it is the ultimate destination (in which case headers with no role or the explicit UltimateDestination role will be included), and any non-standard roles it supports. Headers targeted to "next" will always be included, and those targeted to "none" (for SOAP 1.2) will never be included.

    Parameters:
      `rolePlayer` - the `RolePlayer` object specifying the role configuration
    Returns:
      an iterator over all the `SOAPHeaderBlock` objects the RolePlayer should process

  - ### examineHeaderBlocks

    Iterator<SOAPHeaderBlock> examineHeaderBlocks(String role)
    Returns a list of all the `SOAPHeaderBlock` objects in this `SOAPHeader` object that have the the specified role. An role is a global attribute that indicates the intermediate parties to whom the message should be sent. A role receives the message and then sends it to the next role. The default role is the ultimate intended recipient for the message, so if no role attribute is included in a `SOAPHeaderBlock` object, the message is sent to its ultimate destination.
    Parameters:
      `role` - the URI of the role for which to search
    Returns:
      an iterator over all the `SOAPHeaderBlock` objects that contain the specified role
    See Also:
      - `extractHeaderBlocks(String)`

  - ### extractHeaderBlocks

    Iterator<SOAPHeaderBlock> extractHeaderBlocks(String role)
    Returns a list of all the `SOAPHeaderBlock` objects in this `SOAPHeader` object that have the the specified role and detaches them from this `SOAPHeader` object.

    This method allows an role 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 role.

    Parameters:
      `role` - the URI of the role for which to search
    Returns:
      an iterator over all the `SOAPHeaderBlock` objects that contain the specified role
    See Also:
      - `examineHeaderBlocks(String)`

  - ### examineMustUnderstandHeaderBlocks

    Iterator<SOAPHeaderBlock> examineMustUnderstandHeaderBlocks(String role)
    Returns an iterator over all the `SOAPHeaderBlock` objects in this `SOAPHeader` object that have the specified role and that have a `MustUnderstand` attribute whose value is equivalent to `true`.
    Parameters:
      `role` - the URI of the role for which to search
    Returns:
      an iterator over all the `SOAPHeaderBlock` objects that contain the specified role and are marked as MustUnderstand.

  - ### examineAllHeaderBlocks

    Iterator<SOAPHeaderBlock> examineAllHeaderBlocks()
    Returns an iterator over all the `SOAPHeaderBlock` objects in this `SOAPHeader` object.
    Returns:
      An iterator over all the `SOAPHeaderBlock` objects contained by this `SOAPHeader`. If there are no header blocks then an empty iterator is returned.

  - ### extractAllHeaderBlocks

    Iterator<SOAPHeaderBlock> extractAllHeaderBlocks()
    Returns an iterator over all the `SOAPHeaderBlock` objects in this `SOAPHeader` object and detaches them from this `SOAPHeader` object.
    Returns:
      an iterator over all the `SOAPHeaderBlock` objects contained by this `SOAPHeader`

  - ### getHeaderBlocksWithNSURI

    ArrayList<SOAPHeaderBlock> getHeaderBlocksWithNSURI(String nsURI)
    Deprecated.
    Use `getHeaderBlocksWithNamespaceURI(String)` instead.
    Return all the Headers that has the Namespace URI to given NS URI.
    Parameters:
      `nsURI` -
    Returns:
      Returns ArrayList.

  - ### getHeaderBlocksWithNamespaceURI

    Iterator<SOAPHeaderBlock> getHeaderBlocksWithNamespaceURI(String uri)
    Get all header blocks in the given namespace. This is similar to `OMContainer.getChildrenWithNamespaceURI(String)`, but ensures that the returned nodes are `SOAPHeaderBlock` instances.
    Parameters:
      `uri` - the namespace URI
    Returns:
      an iterator with the matching header blocks

  - ### getHeaderBlocksWithName

    Iterator<SOAPHeaderBlock> getHeaderBlocksWithName(QName name)
    Get all header blocks with the given name. This is similar to `OMContainer.getChildrenWithName(QName)`, but ensures that the returned nodes are `SOAPHeaderBlock` instances.
    Parameters:
      `name` - the QName specifying the namespace URI and local name to match.
    Returns:
      an iterator with the matching header blocks

  - ### getHeadersToProcess

    Iterator<SOAPHeaderBlock> getHeadersToProcess(RolePlayer rolePlayer, String namespace)
    Get the appropriate set of headers for a RolePlayer and a particular namespace.

    The `RolePlayer` indicates whether it is the ultimate destination (in which case headers with no role or the explicit UltimateDestination role will be included), and any non-standard roles it supports. Headers targeted to "next" will always be included, and those targeted to "none" (for SOAP 1.2) will never be included.

    This version of the API allows us to iterate only once over the headers searching for a particular namespace for headers targeted at "us".

    Parameters:
      `rolePlayer` - the `RolePlayer` object specifying the role configuration
      `namespace` - if specified, we'll only return headers from this namespace
    Returns:
      an iterator over all the `SOAPHeaderBlock` objects the RolePlayer should process