org.apache.xmlbeans.impl.soap

## Interface SOAPEnvelope

All Superinterfaces:
  Element, Node, SOAPElement

    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");

### Field Summary

### Fields inherited from interface org.w3c.dom.Node

`ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE`

### Method Summary

All Methods Instance Methods Abstract Methods
`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(String localName)` Creates a new `Name` object initialized with the given local name.
`Name` `createName(String localName, String prefix, 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 org.apache.xmlbeans.impl.soap.SOAPElement

`addAttribute, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addNamespaceDeclaration, addTextNode, getAllAttributes, getAttributeValue, getChildElements, getChildElements, getElementName, getEncodingStyle, getNamespacePrefixes, getNamespaceURI, getVisibleNamespacePrefixes, removeAttribute, removeContents, removeNamespaceDeclaration, setEncodingStyle`

### Methods inherited from interface org.apache.xmlbeans.impl.soap.Node

`detachNode, getParentElement, getValue, recycleNode, setParentElement, setValue`

### Methods inherited from interface org.w3c.dom.Element

`getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, getSchemaTypeInfo, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setIdAttribute, setIdAttributeNode, setIdAttributeNS`

### Methods inherited from interface org.w3c.dom.Node

`appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData`

### Method Detail

#### createName

    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` - 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

    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` - 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

    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

    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

    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

    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