SOAPEnvelope (Java EE 5)

Java EE API

previous page next page
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap Interface SOAPEnvelope

All Superinterfaces:
Element, Node, SOAPElement
public interface SOAPEnvelope
extends SOAPElement

Implements: SOAPElement

SOAPPart 对象的 SOAPHeader 和 SOAPBody 部分的容器。默认情况下，使用带有 SOAPEnvelope 对象的 SOAPPart 对象创建 SOAPMessage 对象。SOAPEnvelope 对象默认带有空 SOAPBody 对象和空 SOAPHeader 对象。SOAPBody 对象是必需的，SOAPHeader 对象虽然是可选的，但在大多数情况下都会用到。如果不需要 SOAPHeader 对象，则可以删除该对象（稍后将显示该操作）。

客户端可以通过调用方法 SOAPEnvelope.getHeader 和 SOAPEnvelope.getBody 来访问 SOAPHeader 和 SOAPBody 对象。以下代码行首先使用 SOAPMessage 对象 message 获取 SOAPPart 对象 sp，然后使用后者获取 SOAPEnvelope 对象 se，最后调用上述的两种方法。 

SOAPPart sp = message.getSOAPPart();
SOAPEnvelope se = sp.getEnvelope();
SOAPHeader sh = se.getHeader();
SOAPBody sb = se.getBody();

检索 SOAPEnvelope 对象当前的正文或头，然后将其删除并添加一个新正文或头，这样就能更改该对象的正文或头。javax.xml.soap.Node 方法 deleteNode 删除调用它的 XML 元素（节点）。例如，以下代码行删除由方法 getBody 检索的 SOAPBody 对象。 

se.getBody().detachNode();
要创建用来替换被移除对象的 SOAPHeader 对象，客户端应使用方法 SOAPEnvelope.addHeader，该方法创建一个新头并将其添加到 SOAPEnvelope 对象。类似地，方法 addBody 创建一个新 SOAPBody 对象并将其添加到 SOAPEnvelope 对象。以下代码片段检索当前的头，然后将其删除并添加一个新头。接下来检索当前的正文，然后将其删除并添加一个新正文。 
SOAPPart sp = message.getSOAPPart();
SOAPEnvelope se = sp.getEnvelope();
se.getHeader().detachNode();
SOAPHeader sh = se.addHeader();
se.getBody().detachNode();
SOAPBody sb = se.addBody();
在已经存在的情况下添加 SOAPBody 或 SOAPHeader 是错误的。

SOAPEnvelope 接口提供了三种创建 Name 对象的方法。第一种方法使用本地名称、名称空间前缀以及名称空间 URI 创建 Name 对象。第二种方法使用本地名称和名称空间前缀创建 Name 对象，第三种方法只使用本地名称创建 Name 对象。以下代码行（其中 se 是一个 SOAPEnvelope 对象）创建带有所有三个元素的新 Name 对象。 

Name name = se.createName("GetLastTradePrice", "WOMBAT",
"http://www.wombat.org/trader");
英文文档：

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

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
 
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
 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 javax.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
 
Methods inherited from interface javax.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 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

public Name createName(String localName, String prefix, String uri) throws SOAPException
创建使用给定本地名称、名称空间前缀和名称空间 URL 初始化的新 Name 对象。

此工厂方法创建在 SOAP/XML 文档中使用的 Name 对象。

localName 给出本地名称的 String
prefix 给出名称空间前缀的 String
uri 给出名称空间 URI 的 String
return 使用给定本地名称、名称空间前缀和名称空间 URI 初始化的 Name 对象
ThrowsSOAPException: 如果存在 SOAP 错误

英文文档：

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

public Name createName(String localName) throws SOAPException
创建使用给定本地名称初始化的新 Name 对象。

此工厂方法创建在 SOAP/XML 文档中使用的 Name 对象。

localName 给出本地名称的 String
return 使用给定本地名称初始化的 Name 对象
ThrowsSOAPException: 如果存在 SOAP 错误

英文文档：

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

public SOAPHeader getHeader() throws SOAPException
返回此 SOAPEnvelope 对象的 SOAPHeader 对象。

默认情况下，使用包含空 SOAPHeader 对象的 SOAPEnvelope 对象创建新 SOAPMessage 对象。因此，只要没有移除了头且尚未添加新头，方法 getHeader 将总是返回 SOAPHeader 对象。

return SOAPHeader 对象，如果没有该对象，则返回 null
ThrowsSOAPException: 如果在获取 SOAPHeader 对象时出现问题

英文文档：

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

public SOAPBody getBody() throws SOAPException
返回与此 SOAPEnvelope 对象关联的 SOAPBody 对象。

默认情况下，使用包含空 SOAPBody 对象的 SOAPEnvelope 对象创建 SOAPMessage 对象。因此，只要没有移除了正文且尚未添加新正文，方法 getBody 将总是返回 SOAPBody 对象。

return 此 SOAPEnvelope 对象的 SOAPBody 的对象，如果没有该对象，则返回 null
ThrowsSOAPException: 如果在获取 SOAPBody 对象时出现问题

英文文档：

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

public SOAPHeader addHeader() throws SOAPException
创建一个 SOAPHeader 对象，并将其设置为此 SOAPEnvelope 对象的 SOAPHeader 对象。

当信封已包含头时，添加头是非法的。因此，此方法应该在移除了现有的头之后调用。

return 新的 SOAPHeader 对象
ThrowsSOAPException: 如果此 SOAPEnvelope 对象已包含一个有效的 SOAPHeader 对象

英文文档：

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

public SOAPBody addBody() throws SOAPException
创建一个 SOAPBody 对象，并将其设置为此 SOAPEnvelope 对象的 SOAPBody 对象。

当信封已包含正文时，添加正文是非法的。因此，此方法应该在移除了现有的正文之后调用。

return 新的 SOAPBody 对象
ThrowsSOAPException: 如果此 SOAPEnvelope 对象已包含一个有效的 SOAPBody 对象

英文文档：

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
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.

一看就知道只有菜鸟才干这么无知的事啦。

PS : 未经我党受权你也可自由散发此文档。 如有任何错误请自行修正；若因此而造成任何损失请直接找人民主席，请勿与本人联系。谢谢！

previous page start next page