javax.xml.soap API 1.4.0 · javax.xml.soap.SOAPEnvelope

The container for the SOAPHeader and SOAPBody portions of a 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 deleteNode deletes 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

Modifier and Type	Method and Description
public SOAPBody	Returns: the new `SOAPBody` object addBody() Creates a `SOAPBody` object and sets it as the `SOAPBody` object for this `SOAPEnvelope` object.
public SOAPHeader	Returns: the new `SOAPHeader` object addHeader() Creates a `SOAPHeader` object and sets it as the `SOAPHeader` object for this `SOAPEnvelope` object.
public Name	Returns: a `Name` object initialized with the given local name, namespace prefix, and namespace URI createName(String a `String` giving the local name localName, String a `String` giving the prefix of the namespace prefix, String a `String` giving the URI of the namespace uri) Creates a new `Name` object initialized with the given local name, namespace prefix, and namespace URI.
public Name	Returns: a `Name` object initialized with the given local name createName(String a `String` giving the local name localName) Creates a new `Name` object initialized with the given local name.
public SOAPBody	Returns: the `SOAPBody` object for this `SOAPEnvelope` object or `null` if there is none getBody() Returns the `SOAPBody` object associated with this `SOAPEnvelope` object.
public SOAPHeader	Returns: the `SOAPHeader` object or `null` if there is none getHeader() Returns the `SOAPHeader` object for this `SOAPEnvelope` object.

Method Detail

addBody back to summary

addBody	back to summary
public SOAPBody addBody() throws SOAPException Creates a `SOAPBody` object and sets it as the `SOAPBody` object for this `SOAPEnvelope` 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:SOAPBody the new `SOAPBody` object Exceptions SOAPException: if this `SOAPEnvelope` object already contains a valid `SOAPBody` object

public SOAPBody addBody() throws SOAPException

Creates a SOAPBody object and sets it as the SOAPBody object for this SOAPEnvelope 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:SOAPBody

the new SOAPBody object

Exceptions

SOAPException:: if this SOAPEnvelope object already contains a valid SOAPBody object

addHeader back to summary

addHeader	back to summary
public SOAPHeader addHeader() throws SOAPException Creates a `SOAPHeader` object and sets it as the `SOAPHeader` object for this `SOAPEnvelope` 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:SOAPHeader the new `SOAPHeader` object Exceptions SOAPException: if this `SOAPEnvelope` object already contains a valid `SOAPHeader` object

public SOAPHeader addHeader() throws SOAPException

Creates a SOAPHeader object and sets it as the SOAPHeader object for this SOAPEnvelope 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:SOAPHeader

the new SOAPHeader object

Exceptions

SOAPException:: if this SOAPEnvelope object already contains a valid SOAPHeader object

createName back to summary

createName	back to summary
public Name createName(String localName, String prefix, String uri) throws SOAPException Creates a new `Name` object initialized with the given local name, namespace prefix, and namespace URI. This factory method creates `Name` objects for use in the SOAP/XML document. Parameters localName:String a `String` giving the local name prefix:String a `String` giving the prefix of the namespace uri:String a `String` giving the URI of the namespace Returns:Name a `Name` object initialized with the given local name, namespace prefix, and namespace URI Exceptions SOAPException: if there is a SOAP error

public Name createName(String localName, String prefix, String uri) throws SOAPException

Creates a new Name object initialized with the given local name, namespace prefix, and namespace URI.

This factory method creates Name objects for use in the SOAP/XML document.

Parameters

localName:String: a String giving the local name
prefix:String: a String giving the prefix of the namespace
uri:String: a String giving the URI of the namespace

Returns:Name

a Name object initialized with the given local name, namespace prefix, and namespace URI

Exceptions

SOAPException:: if there is a SOAP error

createName back to summary

createName	back to summary
public Name createName(String localName) throws SOAPException Creates a new `Name` object initialized with the given local name. This factory method creates `Name` objects for use in the SOAP/XML document. Parameters localName:String a `String` giving the local name Returns:Name a `Name` object initialized with the given local name Exceptions SOAPException: if there is a SOAP error

public Name createName(String localName) throws SOAPException

Creates a new Name object initialized with the given local name.

This factory method creates Name objects for use in the SOAP/XML document.

Parameters

localName:String: a String giving the local name

Returns:Name

a Name object initialized with the given local name

Exceptions

SOAPException:: if there is a SOAP error

getBody back to summary

getBody	back to summary
public SOAPBody getBody() throws SOAPException Returns the `SOAPBody` object associated with this `SOAPEnvelope` object. A new `SOAPMessage` object is by default created with a `SOAPEnvelope` object that contains an empty `SOAPBody` object. As a result, the method `getBody` will always return a `SOAPBody` object unless the body has been removed and a new one has not been added. Returns:SOAPBody the `SOAPBody` object for this `SOAPEnvelope` object or `null` if there is none Exceptions SOAPException: if there is a problem obtaining the `SOAPBody` object

public SOAPBody getBody() throws SOAPException

Returns the SOAPBody object associated with this SOAPEnvelope object.

A new SOAPMessage object is by default created with a SOAPEnvelope object that contains an empty SOAPBody object. As a result, the method getBody will always return a SOAPBody object unless the body has been removed and a new one has not been added.

Returns:SOAPBody

the SOAPBody object for this SOAPEnvelope object or null if there is none

Exceptions

SOAPException:: if there is a problem obtaining the SOAPBody object

getHeader back to summary

getHeader	back to summary
public SOAPHeader getHeader() throws SOAPException Returns the `SOAPHeader` object for this `SOAPEnvelope` object. A new `SOAPMessage` object is by default created with a `SOAPEnvelope` object that contains an empty `SOAPHeader` object. As a result, the method `getHeader` will always return a `SOAPHeader` object unless the header has been removed and a new one has not been added. Returns:SOAPHeader the `SOAPHeader` object or `null` if there is none Exceptions SOAPException: if there is a problem obtaining the `SOAPHeader` object

public SOAPHeader getHeader() throws SOAPException

Returns the SOAPHeader object for this SOAPEnvelope object.

A new SOAPMessage object is by default created with a SOAPEnvelope object that contains an empty SOAPHeader object. As a result, the method getHeader will always return a SOAPHeader object unless the header has been removed and a new one has not been added.

Returns:SOAPHeader

the SOAPHeader object or null if there is none

Exceptions

SOAPException:: if there is a problem obtaining the SOAPHeader object

public Interface SOAPEnvelope

Method Summary

Method Detail