Interface SOAPEnvelope
-
- All Superinterfaces:
Element
,Node
,Node
,SOAPElement
public interface SOAPEnvelope extends SOAPElement
The container for the SOAPHeader and SOAPBody portions of aSOAPPart
object. By default, aSOAPMessage
object is created with aSOAPPart
object that has aSOAPEnvelope
object. TheSOAPEnvelope
object by default has an emptySOAPBody
object and an emptySOAPHeader
object. TheSOAPBody
object is required, and theSOAPHeader
object, though optional, is used in the majority of cases. If theSOAPHeader
object is not needed, it can be deleted, which is shown later.A client can access the
SOAPHeader
andSOAPBody
objects by calling the methodsSOAPEnvelope.getHeader
andSOAPEnvelope.getBody
. The following lines of code use these two methods after starting with theSOAPMessage
object message to get theSOAPPart
object sp, which is then used to get theSOAPEnvelope
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. Thejakarta.xml.soap.Node
methoddetachNode
deletes the XML element (node) on which it is called. For example, the following line of code deletes theSOAPBody
object that is retrieved by the methodgetBody
.
To create ase.getBody().detachNode();
SOAPHeader
object to replace the one that was removed, a client uses the methodSOAPEnvelope.addHeader
, which creates a new header and adds it to theSOAPEnvelope
object. Similarly, the methodaddBody
creates a newSOAPBody
object and adds it to theSOAPEnvelope
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.
It is an error to add aSOAPPart sp = message.getSOAPPart(); SOAPEnvelope se = sp.getEnvelope(); se.getHeader().detachNode(); SOAPHeader sh = se.addHeader(); se.getBody().detachNode(); SOAPBody sb = se.addBody();
SOAPBody
orSOAPHeader
object if one already exists.The
SOAPEnvelope
interface provides three methods for creatingName
objects. One method createsName
objects with a local name, a namespace prefix, and a namesapce URI. The second method createsName
objects with a local name and a namespace prefix, and the third createsName
objects with just a local name. The following line of code, in which se is aSOAPEnvelope
object, creates a newName
object with all three.Name name = se.createName("GetLastTradePrice", "WOMBAT", "http://www.wombat.org/trader");
- Since:
- 1.6
-
-
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 Description SOAPBody
addBody()
Creates aSOAPBody
object and sets it as theSOAPBody
object for thisSOAPEnvelope
object.SOAPHeader
addHeader()
Creates aSOAPHeader
object and sets it as theSOAPHeader
object for thisSOAPEnvelope
object.Name
createName(String localName)
Creates a newName
object initialized with the given local name.Name
createName(String localName, String uri)
Creates a newName
object initialized with the given local name and namespace prefix.Name
createName(String localName, String prefix, String uri)
Creates a newName
object initialized with the given local name, namespace prefix, and namespace URI.SOAPBody
getBody()
Returns theSOAPBody
object associated with thisSOAPEnvelope
object.SOAPHeader
getHeader()
Returns theSOAPHeader
object for thisSOAPEnvelope
object.-
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 jakarta.xml.soap.Node
detachNode, getParentElement, getValue, recycleNode, setParentElement, setValue
-
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
-
Methods inherited from interface jakarta.xml.soap.SOAPElement
addAttribute, addAttribute, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addNamespaceDeclaration, addTextNode, createQName, getAllAttributes, getAllAttributesAsQNames, getAttributeValue, getAttributeValue, getChildElements, getChildElements, getChildElements, getElementName, getElementQName, getEncodingStyle, getNamespacePrefixes, getNamespaceURI, getVisibleNamespacePrefixes, removeAttribute, removeAttribute, removeContents, removeNamespaceDeclaration, setElementQName, setEncodingStyle
-
-
-
-
Method Detail
-
createName
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 creates
Name
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
-
createName
Name createName(String localName, String uri) throws SOAPException
Creates a newName
object initialized with the given local name and namespace prefix.This factory method creates
Name
objects for use in the SOAP/XML document.- Parameters:
localName
- aString
giving the local nameuri
- 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
-
createName
Name createName(String localName) throws SOAPException
Creates a newName
object initialized with the given local name.This factory method creates
Name
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
-
getHeader
SOAPHeader getHeader() throws SOAPException
Returns theSOAPHeader
object for thisSOAPEnvelope
object.A new
SOAPMessage
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
-
getBody
SOAPBody getBody() throws SOAPException
Returns theSOAPBody
object associated with thisSOAPEnvelope
object.A new
SOAPMessage
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
-
addHeader
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
-
addBody
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
-
-