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);
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.
name
- a Name
object with
the name of the new SOAPHeaderElement
object
- the new
SOAPHeaderElement
object that
was inserted into this SOAPHeader
object
SOAPException
- if a SOAP error occurs
examineAllHeaderElements
public Iterator examineAllHeaderElements()
Returns an Iterator
over all the
SOAPHeaderElement
objects in this SOAPHeader
object.
- an
Iterator
object over all the
SOAPHeaderElement
objects contained by this
SOAPHeader
examineHeaderElements
public Iterator examineHeaderElements(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.
actor
- a String
giving the
URI of the actor for which to search
- an
Iterator
object over all the
SOAPHeaderElement
objects that contain the
specified actor
extractHeaderElements(java.lang.String)
examineMustUnderstandHeaderElements
public 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
.
actor
- a String
giving the URI of the actor for which
to search
- an
Iterator
object over all the
SOAPHeaderElement
objects that contain the
specified actor and are marked as MustUnderstand
extractAllHeaderElements
public Iterator extractAllHeaderElements()
Returns an Iterator
over all the
SOAPHeaderElement
objects in this SOAPHeader
object and detaches them from this SOAPHeader
object.
- an
Iterator
object over all the
SOAPHeaderElement
objects contained by this
SOAPHeader
extractHeaderElements
public Iterator extractHeaderElements(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.
actor
- a String
giving the
URI of the actor for which to search
- an
Iterator
object over all the
SOAPHeaderElement
objects that contain the
specified actor
examineHeaderElements(java.lang.String)