javax.xml.soap
接口 SOAPEnvelope

所有超级接口：

Element, Node, SOAPElement

public interface SOAPEnvelope
extends 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();
 

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

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

Name name = se.createName("GetLastTradePrice", "WOMBAT",
"https://www.wombat.org/trader");
 

createName

Name createName(String localName,
                String prefix,
                String uri)
                throws SOAPException

创建使用给定本地名称、名称空间前缀和名称空间 URL 初始化的新 Name 对象。

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

参数：

localName - 给出本地名称的 String

prefix - 给出名称空间前缀的 String

uri - 给出名称空间 URI 的 String

返回：

使用给定本地名称、名称空间前缀和名称空间 URL 初始化的 Name 对象

抛出：

SOAPException - 如果存在 SOAP 错误

createName

Name createName(String localName)
                throws SOAPException

创建使用给定本地名称初始化的新 Name 对象。

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

参数：

localName - 给出本地名称的 String

返回：

使用给定本地名称初始化的 Name 对象

抛出：

SOAPException - 如果存在 SOAP 错误

getHeader

SOAPHeader getHeader()
                     throws SOAPException

返回此 SOAPEnvelope 对象的 SOAPHeader 对象。

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

返回：

SOAPHeader 对象，如果没有该对象，则返回 null

抛出：

SOAPException - 如果在获取 SOAPHeader 对象时出现问题

getBody

SOAPBody getBody()
                 throws SOAPException

返回与此 SOAPEnvelope 对象关联的 SOAPBody 对象。

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

返回：

此 SOAPEnvelope 对象的 SOAPBody 的对象，如果没有该对象，则返回 null

抛出：

SOAPException - 如果在获取 SOAPBody 对象时出现问题

addHeader

SOAPHeader addHeader()
                     throws SOAPException

创建一个 SOAPHeader 对象，并将其设置为此 SOAPEnvelope 对象的 SOAPHeader 对象。

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

返回：

新的 SOAPHeader 对象

抛出：

SOAPException - 如果此 SOAPEnvelope 对象已包含一个有效的 SOAPHeader 对象

addBody

SOAPBody addBody()
                 throws SOAPException

创建一个 SOAPBody 对象，并将其设置为此 SOAPEnvelope 对象的 SOAPBody 对象。

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

返回：

新的 SOAPBody 对象

抛出：

SOAPException - 如果此 SOAPEnvelope 对象已包含一个有效的 SOAPBody 对象

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。