Prev Class | Next Class | Frames | No Frames |
Summary: Nested | Field | Method | Constr | Detail: Nested | Field | Method | Constr |
public interface SOAPEnvelope
extends SOAPElement
SOAPPart
object. By default, a
SOAPMessage
object is created with a
SOAPPart
object that has a SOAPEnvelope
object. The SOAPEnvelope
object by default has an
empty SOAPBody
object and an empty
SOAPHeader
object. The SOAPBody
object is
required, and the SOAPHeader
object, though
optional, is used in the majority of cases. If the
SOAPHeader
object is not needed, it can be deleted,
which is shown later.
A client can access the SOAPHeader
and
SOAPBody
objects by calling the methods
SOAPEnvelope.getHeader
and
SOAPEnvelope.getBody
. The following lines of code use
these two methods after starting with the
SOAPMessage
object message to get the
SOAPPart
object sp, which is then used to get the
SOAPEnvelope
object se.
SOAPPart sp = message.getSOAPPart(); SOAPEnvelope se = sp.getEnvelope(); SOAPHeader sh = se.getHeader(); SOAPBody sb = se.getBody();It is possible to change the body or header of a
SOAPEnvelope
object by retrieving the current one,
deleting it, and then adding a new body or header. The
javax.xml.soap.Node
method detachNode
detaches the XML element (node) on which it is called. For
example, the following line of code deletes the
SOAPBody
object that is retrieved by the method
getBody
.
se.getBody().detachNode();To create a
SOAPHeader
object to replace the one
that was removed, a client uses the method
SOAPEnvelope.addHeader
, which creates a new header and
adds it to the SOAPEnvelope
object. Similarly, the
method addBody
creates a new SOAPBody
object and adds it to the SOAPEnvelope
object. The
following code fragment retrieves the current header, removes
it, and adds a new one. Then it retrieves the current body,
removes it, and adds a new one.
SOAPPart sp = message.getSOAPPart(); SOAPEnvelope se = sp.getEnvelope(); se.getHeader().detachNode(); SOAPHeader sh = se.addHeader(); se.getBody().detachNode(); SOAPBody sb = se.addBody();It is an error to add a
SOAPBody
or
SOAPHeader
object if one already exists.
The SOAPEnvelope
interface provides three
methods for creating Name
objects. One method
creates Name
objects with a local name, a
namespace prefix, and a namesapce URI. The second method
creates Name
objects with a local name and a
namespace prefix, and the third creates Name
objects with just a local name. The following line of code, in
which se is a SOAPEnvelope
object, creates
a new Name
object with all three.
Name name = se.createName("GetLastTradePrice", "WOMBAT", "http://www.wombat.org/trader");
Method Summary | |
SOAPBody |
|
SOAPHeader |
|
Name |
|
Name |
|
SOAPBody |
|
SOAPHeader |
|
Methods inherited from interface javax.xml.soap.Node | |
detachNode , getParentElement , getValue , recycleNode , setParentElement , setValue |
public SOAPBody addBody() throws SOAPException
Creates aSOAPBody
object and sets it as theSOAPBody
object for thisSOAPEnvelope
object. It is illegal to add a body when the envelope already contains a body. Therefore, this method should be called only after the existing body has been removed.
- Returns:
- the new
SOAPBody
object
- Throws:
SOAPException
- if thisSOAPEnvelope
object already contains a validSOAPBody
object
public SOAPHeader addHeader() throws SOAPException
Creates aSOAPHeader
object and sets it as theSOAPHeader
object for thisSOAPEnvelope
object. It is illegal to add a header when the envelope already contains a header. Therefore, this method should be called only after the existing header has been removed.
- Returns:
- the new
SOAPHeader
object
- Throws:
SOAPException
- if thisSOAPEnvelope
object already contains a validSOAPHeader
object
public Name createName(String localName) throws SOAPException
Creates a newName
object initialized with the given local name. This factory method createsName
objects for use in the SOAP/XML document.
- Parameters:
localName
- aString
giving the local name
- Returns:
- a
Name
object initialized with the given local name
- Throws:
SOAPException
- if there is a SOAP error
public Name createName(String localName, String prefix, String uri) throws SOAPException
Creates a newName
object initialized with the given local name, namespace prefix, and namespace URI. This factory method createsName
objects for use in the SOAP/XML document.
- Parameters:
localName
- aString
giving the local nameprefix
- aString
giving the prefix of the namespaceuri
- aString
giving the URI of the namespace
- Returns:
- a
Name
object initialized with the given local name, namespace prefix, and namespace URI
- Throws:
SOAPException
- if there is a SOAP error
public SOAPBody getBody() throws SOAPException
Returns theSOAPBody
object associated with thisSOAPEnvelope
object. A newSOAPMessage
object is by default created with aSOAPEnvelope
object that contains an emptySOAPBody
object. As a result, the methodgetBody
will always return aSOAPBody
object unless the body has been removed and a new one has not been added.
- Returns:
- the
SOAPBody
object for thisSOAPEnvelope
object ornull
if there is none
- Throws:
SOAPException
- if there is a problem obtaining theSOAPBody
object
public SOAPHeader getHeader() throws SOAPException
Returns theSOAPHeader
object for thisSOAPEnvelope
object. A newSOAPMessage
object is by default created with aSOAPEnvelope
object that contains an emptySOAPHeader
object. As a result, the methodgetHeader
will always return aSOAPHeader
object unless the header has been removed and a new one has not been added.
- Returns:
- the
SOAPHeader
object ornull
if there is none
- Throws:
SOAPException
- if there is a problem obtaining theSOAPHeader
object