## javax.xml.soap
Interface SOAPEnvelope

All Superinterfaces:
  Node, SOAPElement

All Known Implementing Classes:
  SOAPEnvelope

public interface SOAPEnvelope
extends SOAPElement

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 `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` `addBody()` Creates a `SOAPBody` object and sets it as the `SOAPBody` object for this `SOAPEnvelope` object.
`SOAPHeader` `addHeader()` Creates a `SOAPHeader` object and sets it as the `SOAPHeader` object for this `SOAPEnvelope` object.
`Name` `createName(java.lang.String localName)` Creates a new `Name` object initialized with the given local name.
`Name` `createName(java.lang.String localName, java.lang.String prefix, java.lang.String uri)` Creates a new `Name` object initialized with the given local name, namespace prefix, and namespace URI.
`SOAPBody` `getBody()` Returns the `SOAPBody` object associated with this `SOAPEnvelope` object.
`SOAPHeader` `getHeader()` Returns the `SOAPHeader` object for this `SOAPEnvelope` object.

Methods inherited from interface javax.xml.soap.SOAPElement
`addAttribute, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addNamespaceDeclaration, addTextNode, getAllAttributes, getAttributeValue, getChildElements, getChildElements, getElementName, getEncodingStyle, getNamespacePrefixes, getNamespaceURI, removeAttribute, removeNamespaceDeclaration, setEncodingStyle`

Methods inherited from interface javax.xml.soap.Node
`detachNode, getParentElement, getValue, recycleNode, setParentElement`

Method Detail

### createName

    public Name createName(java.lang.String localName,
                           java.lang.String prefix,
                           java.lang.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` - a `String` giving the local name
    `prefix` - a `String` giving the prefix of the namespace
    `uri` - a `String` 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

### createName

    public Name createName(java.lang.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` - a `String` giving the local name
  Returns:
    a `Name` object initialized with the given local name
  Throws:
    `SOAPException` - if there is a SOAP error

### getHeader

    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:
    the `SOAPHeader` object or `null` if there is none
  Throws:
    `SOAPException` - if there is a problem obtaining the `SOAPHeader` object

### getBody

    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:
    the `SOAPBody` object for this `SOAPEnvelope` object or `null` if there is none
  Throws:
    `SOAPException` - if there is a problem obtaining the `SOAPBody` object

### addHeader

    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:
    the new `SOAPHeader` object
  Throws:
    `SOAPException` - if this `SOAPEnvelope` object already contains a valid `SOAPHeader` object

### addBody

    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:
    the new `SOAPBody` object
  Throws:
    `SOAPException` - if this `SOAPEnvelope` object already contains a valid `SOAPBody` object

Copyright © 2003 Apache Web Services Project. All Rights Reserved.