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
    Modifier and Type | Method and Description
    --- | ---
    `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