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

Class SOAPMessage



  • public abstract class SOAPMessage
    extends Object
    所有SOAP消息的根类。 如在“线”上传输的,SOAP消息是XML文档或MIME消息,其第一个主体部分是XML / SOAP文档。

    SOAPMessage对象由SOAP部分和可选的一个或多个附件组成。 SOAPMessage对象的SOAP部分是一个SOAPPart对象,其中包含用于消息路由和标识的信息,并且可以包含应用程序特定的内容。 消息的SOAP部分中的所有数据必须是XML格式。

    新的SOAPMessage对象默认包含以下内容:

    • A SOAPPart对象
    • A SOAPEnvelope对象
    • A SOAPBody对象
    • A SOAPHeader对象
    消息的SOAP部分可以通过调用方法SOAPMessage.getSOAPPart()来检索。 SOAPEnvelope对象检索SOAPPart对象,并使用SOAPEnvelope对象检索SOAPBodySOAPHeader对象。
       SOAPPart sp = message.getSOAPPart(); SOAPEnvelope se = sp.getEnvelope(); SOAPBody sb = se.getBody(); SOAPHeader sh = se.getHeader();  

    除了强制性的SOAPPart对象外, SOAPMessage对象可能包含零个或多个AttachmentPart对象,每个对象都包含应用程序特定的数据。 SOAPMessage接口提供了创建AttachmentPart对象的方法,并将其添加到一个SOAPMessage对象。 收到SOAPMessage对象的SOAPMessage可以通过检索各个附件部件来检查其内容。

    与SOAP消息的其余部分不同,附件不需要是XML格式,因此可以是从简单文本到图像文件的任何内容。 因此,任何不是XML格式的邮件内容必须在AttachmentPart对象中。

    一个MessageFactory对象可以创建SOAPMessage对象与专门到SAAJ的具体实现或应用程序的行为。 例如, MessageFactory对象可能产生符合特定配置文件(如ebXML)的SOAPMessage对象。 在这种情况下, MessageFactory对象可能会产生使用ebXML头部初始化的SOAPMessage对象。

    为了确保向后的源兼容性,在SAAJ规范版本1.1之后添加到此类的方法都是具体而不是抽象的,它们都具有默认实现。 除非在JavaDocs中为这些方法另有说明,默认实现只需抛出一个UnsupportedOperationException ,并且SAAJ实现代码必须用提供指定行为的方法覆盖它们。 然而,传统的客户端代码没有这种限制,只要没有声明符合规范的某些更新版本,而不是最初编写的。 扩展SOAPMessage类的遗留类可以编译和/或针对后续版本的SAAJ API进行运行,而无需修改。 如果这样的一个类被正确地实现,那么它将继续正确地相对于它被编写的规范版本而正确地运行。

    从以下版本开始:
    1.6
    另请参见:
    MessageFactoryAttachmentPart
    • 字段详细信息

      • CHARACTER_SET_ENCODING

        public static final String CHARACTER_SET_ENCODING
        指定SOAP消息的字符类型编码。 有效值包括“utf-8”和“utf-16”。 有关其他支持值,请参阅供应商文档 默认值为“utf-8”。
        从以下版本开始:
        1.6,SAAJ 1.2
        另请参见:
        SOAPMessage.setPropertyConstant Field Values
      • WRITE_XML_DECLARATION

        public static final String WRITE_XML_DECLARATION
        指定SOAP消息发送时是否包含XML声明。 唯一有效的值是“true”和“false”。 默认值为“false”。
        从以下版本开始:
        1.6,SAAJ 1.2
        另请参见:
        SOAPMessage.setPropertyConstant Field Values
    • 构造方法详细信息

      • SOAPMessage

        public SOAPMessage​()
    • 方法详细信息

      • setContentDescription

        public abstract void setContentDescription​(String description)
        使用给定的说明设置此 SOAPMessage对象内容的描述。
        参数
        description - 描述此消息内容的 String
        另请参见:
        getContentDescription()
      • getContentDescription

        public abstract String getContentDescription​()
        检索此 SOAPMessage对象内容的描述。
        结果
        一个 String描述此消息或内容 null ,如果没有描述已被设置
        另请参见:
        setContentDescription(java.lang.String)
      • getSOAPPart

        public abstract SOAPPart getSOAPPart​()
        获取此SOAPMessage对象的SOAP部分。

        SOAPMessage对象包含一个或多个附件,SOAP部分必须是消息中的第一个MIME主体部分。

        结果
        SOAPPart对象为此 SOAPMessage对象
      • getSOAPBody

        public SOAPBody getSOAPBody​()
                             throws SOAPException
        获取此 SOAPMessage对象中包含的SOAP Body。
        结果
        SOAPBody对象包含 SOAPMessage对象
        异常
        SOAPException - 如果SOAP主体不存在或无法检索
        从以下版本开始:
        1.6,SAAJ 1.2
      • getSOAPHeader

        public SOAPHeader getSOAPHeader​()
                                 throws SOAPException
        获取此 SOAPMessage对象中包含的SOAP头。
        结果
        这个 SOAPHeader对象包含的 SOAPMessage对象
        异常
        SOAPException - 如果SOAP头不存在或无法检索
        从以下版本开始:
        1.6,SAAJ 1.2
      • removeAllAttachments

        public abstract void removeAllAttachments​()
        删除所有AttachmentPart已经加入到这一对象SOAPMessage对象。

        此方法不接触SOAP部分。

      • countAttachments

        public abstract int countAttachments​()
        获取此消息中附件数量的计数。 此计数不包括SOAP部分。
        结果
        的数量 AttachmentPart对象作为此的一部分 SOAPMessage对象
      • getAttachments

        public abstract Iterator<AttachmentPart> getAttachments​()
        检索所有 AttachmentPart对象是这部分 SOAPMessage对象。
        结果
        在该消息中的所有附件上的迭代器
      • getAttachments

        public abstract Iterator<AttachmentPart> getAttachments​(MimeHeaders headers)
        检索具有与指定标题匹配的标题条目的所有AttachmentPart对象。 请注意,返回的附件除了指定的附件之外还可能包含标题。
        参数
        headers - 一个包含要搜索的MIME标头的 MimeHeaders对象
        结果
        在所有附件上都有一个迭代器,它们具有与给定标题之一匹配的标题
      • removeAttachments

        public abstract void removeAttachments​(MimeHeaders headers)
        删除具有与指定标题匹配的标题条目的所有AttachmentPart对象。 请注意,删除的附件除了指定的附件之外还可能有标题。
        参数
        headers - 一个 MimeHeaders对象,其中包含要搜索的MIME标题
        从以下版本开始:
        1.6,SAAJ 1.3
      • getAttachment

        public abstract AttachmentPart getAttachment​(SOAPElement element)
                                              throws SOAPException
        返回一个AttachmentPart对象,该对象与此SOAPElementnull引用的附件相关联,如果不存在此类附件。 可以通过href中描述的href属性或通过包含URI的单个Text子节点进行引用 ,如WS-I附件配置文件1.0中针对模式类型为ref:swaRef的元素所述 必须支持这两个机制。 通过href属性对引用的支持也意味着该方法也应该支持一个元素,它是一个xop:Include元素( XOP )。 其他参考机制可以由该标准的各个实现来支持。 请联系您的供应商了解详情
        参数
        element - 包含对附件的引用的 SOAPElement
        结果
        参考 AttachmentPart或如果不存在这样的 AttachmentPart AttachmentPart null或在此 SOAPElement未找到引用。
        异常
        SOAPException - 如果尝试访问附件时出现错误
        从以下版本开始:
        1.6,SAAJ 1.3
      • addAttachmentPart

        public abstract void addAttachmentPart​(AttachmentPart attachmentPart)
        将给定的AttachmentPart对象添加到此SOAPMessage对象。 必须先创建一个AttachmentPart对象,然后才能将其添加到消息中。
        参数
        attachmentPart -一个 attachmentPart对象,它是成为本的一部分 SOAPMessage对象
        异常
        IllegalArgumentException - 如果指定的 attachmentPart对象有问题
      • createAttachmentPart

        public abstract AttachmentPart createAttachmentPart​()
        创建一个新的空的AttachmentPart对象。 请注意,使用此新的AttachmentPart对象作为参数必须调用方法addAttachmentPart ,以使其成为此SOAPMessage对象的附件。
        结果
        一个新的 AttachmentPart对象,可以填充并添加到此 SOAPMessage对象
      • createAttachmentPart

        public AttachmentPart createAttachmentPart​(DataHandler dataHandler)
        创建一个 AttachmentPart对象,并使用给定的 DataHandler对象进行填充。
        参数
        dataHandler -在 javax.activation.DataHandler对象将生成此内容 SOAPMessage对象
        结果
        一个新的 AttachmentPart对象,其中包含由给定的 DataHandler对象生成的数据
        异常
        IllegalArgumentException - 如果指定的 DataHandler对象有问题
        另请参见:
        DataHandlerDataContentHandler
      • getMimeHeaders

        public abstract MimeHeaders getMimeHeaders​()
        以传输独立的方式返回此 SOAPMessage对象的所有传输特定MIME标头。
        结果
        一个 MimeHeaders包含对象 MimeHeader对象
      • createAttachmentPart

        public AttachmentPart createAttachmentPart​(Object content,
                                                   String contentType)
        创建一个AttachmentPart对象,并使用指定的内容类型的指定数据进行填充。 Object的类型应对应于Content-Type给出的值。
        参数
        content一个- Object包含用于内容 AttachmentPart要创建的对象
        contentType - 给出内容类型的String对象; 示例是“text / xml”,“text / plain”和“image / jpeg”
        结果
        一个包含给定数据的新的 AttachmentPart对象
        异常
        IllegalArgumentException - 如果contentType与内容对象的类型不匹配,或者如果给定内容对象没有 DataContentHandler对象,则可能会抛出
        另请参见:
        DataHandlerDataContentHandler
      • saveChanges

        public abstract void saveChanges​()
                                  throws SOAPException
        更新此SOAPMessage对象,并对其进行了所有更改。 调用writeTo(OutputStream)时,将自动调用此方法。 但是,如果对已收到的消息或已发送的消息进行更改,则需要显式调用方法saveChanges以保存更改。 方法saveChanges还生成可以回读的任何更改(例如,支持消息标识的配置文件中的MessageId)。 为发送目的而创建的消息中的所有MIME标头只有在saveChanges之后saveChanges

        此外,该方法标记了将来自所有组成部分AttachmentPart对象的数据拉入消息的点。

        异常
        SOAPException - 如果在保存对此消息的更改时出现问题。
      • saveRequired

        public abstract boolean saveRequired​()
        指示这个 SOAPMessage对象是否需要调用方法 saveChanges
        结果
        true如果要求saveChanges ; 否则为false
      • writeTo

        public abstract void writeTo​(OutputStream out)
                              throws SOAPException,
                                     IOException
        将此SOAPMessage对象写入给定的输出流。 外部化格式由具有附件规范的SOAP 1.1定义。

        如果没有附件,只会写出一个XML流。 对于那些有附件的邮件, writeTo写入MIME编码的字节流。

        请注意,此方法不会写入消息的传输特定MIME标头

        参数
        out -在 OutputStream到该对象 SOAPMessage对象将被写入
        异常
        IOException - 如果发生I / O错误
        SOAPException - 如果外部化此SOAP消息时出现问题
      • setProperty

        public void setProperty​(String property,
                                Object value)
                         throws SOAPException
        将指定的值与指定的属性相关联。 如果已经有与此属性相关联的值,则替换旧值。

        有效的属性名称包括WRITE_XML_DECLARATIONCHARACTER_SET_ENCODING 所有这些标准SAAJ属性都以“javax.xml.soap”为前缀。 供应商还可以添加实现特定的属性。 这些属性必须以供应商唯一的包名称作为前缀。

        将属性WRITE_XML_DECLARATION设置为"true"将导致在SOAP消息开始时写出XML声明。 默认值“false”禁止此声明。

        属性CHARACTER_SET_ENCODING默认为值为"utf-8" ,这导致SOAP消息使用UTF-8进行编码。 CHARACTER_SET_ENCODING设置为"utf-16"会导致SOAP消息使用UTF-16进行编码。

        除了UTF-8和UTF-16之外,一些实现可能允许编码。 有关详细信息,请参阅供应商的文档。

        参数
        property - 指定值与之关联的属性。
        value - 与指定属性相关联的值
        异常
        SOAPException - 如果属性名称无法识别。
        从以下版本开始:
        1.6,SAAJ 1.2
      • getProperty

        public Object getProperty​(String property)
                           throws SOAPException
        检索指定属性的值。
        参数
        property - 要检索的属性的名称
        结果
        与该命名属性相关的值,如果没有这样的属性, null
        异常
        SOAPException - 如果属性名称无法识别。
        从以下版本开始:
        1.6,SAAJ 1.2