Module  java.xml.ws
软件包  javax.xml.soap

Interface SOAPEnvelope

  • All Superinterfaces:
    Element ， Node ， Node ， SOAPElement 

    public interface SOAPEnvelope
extends SOAPElement
    用于SOAPHeader和SOAPBody的容器为SOAPPart对象的部分。 默认情况下，使用一个SOAPMessage对象创建一个SOAPPart对象，该对象具有SOAPEnvelope对象。 默认情况下， SOAPEnvelope对象有一个空的SOAPBody对象和一个空的SOAPHeader对象。 SOAPBody对象是必需的，而SOAPHeader对象虽然是可选的，但在大多数情况下都使用。 如果SOAPHeader对象，则可以将其删除，稍后再显示。

    客户端可以通过调用方法SOAPEnvelope.getHeader和SOAPEnvelope.getBody访问SOAPHeader和SOAPBody对象。 下面的代码行使用这两种方法与起始后SOAPMessage对象消息 ，以获得SOAPPart对象SP，然后将其用于获取SOAPEnvelope对象本身 。 

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

    可以通过检索当前的对象，删除它，然后添加一个新的主体或标题来更改SOAPEnvelope对象的正文或标题。 javax.xml.soap.Node方法deleteNode删除javax.xml.soap.Node deleteNode的XML元素（节点）。 例如，以下代码SOAPBody删除由方法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");
    从以下版本开始：
    1.6

    • 方法详细信息

      • createName

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

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

        参数
        localName - 一个 String给出本地名称
        prefix - 一个 String给出命名空间的前缀
        uri - 一个 String给出命名空间的URI
        结果
        一个 Name对象使用给定的本地名称，命名空间前缀和命名空间URI进行初始化
        异常
        SOAPException - 如果存在SOAP错误

      • createName

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

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

        参数
        localName - 一个 String给出本地名称
        结果
        一个 Name对象使用给定的本地名称初始化
        异常
        SOAPException - 如果存在SOAP错误

      • getHeader

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

        新SOAPMessage目标是通过创建一个默认SOAPEnvelope包含空对象SOAPHeader对象。 因此，方法getHeader将始终返回一个SOAPHeader对象，除非标头已经被移除并且尚未添加一个新的对象。

        结果
        SOAPHeader对象或 null如果没有
        异常
        SOAPException - 如果获取 SOAPHeader对象时出现问题

      • getBody

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

        新SOAPMessage目标是通过创建一个默认SOAPEnvelope包含空对象SOAPBody对象。 因此，方法getBody将始终返回一个SOAPBody对象，除非正文已被删除，并且尚未添加新对象。

        结果
        该 SOAPBody对象为 SOAPEnvelope对象或 null如果没有
        异常
        SOAPException - 如果获取 SOAPBody对象有问题

      • addHeader

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

        当信封已经包含标题时添加标题是非法的。 因此，只有在删除现有标题之后，才应该调用此方法。

        结果
        新的 SOAPHeader对象
        异常
        SOAPException - 如果此 SOAPEnvelope对象已经包含有效的 SOAPHeader对象

      • addBody

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

        当信封已经包含身体时添加身体是非法的。 因此，只有在删除现有的身体后才应该调用此方法。

        结果
        新的 SOAPBody对象
        异常
        SOAPException - if this SOAPEnvelope object already contains a valid SOAPBody object