javax.xml.soap
类 SOAPMessage

java.lang.Object
  javax.xml.soap.SOAPMessage

public abstract class SOAPMessage
     

      extends 
      Object
     

所有 SOAP 消息的根类。因为 SOAP 消息是通过“导线”传输的，所以它是 XML 文档或第一个正文部分为 XML/SOAP 文档的 MIME 消息。

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

默认情况下，新的 SOAPMessage 对象包含以下对象：

• 一个 SOAPPart 对象
• 一个 SOAPEnvelope 对象
• 一个 SOAPBody 对象
• 一个 SOAPHeader 对象

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

除强制性 SOAPPart 对象之外，SOAPMessage 对象还可以包含零个或多个 AttachmentPart 对象，每个 AttachmentPart 对象都包含特定于应用程序的数据。SOAPMessage 接口提供了一些用于创建 AttachmentPart 对象的方法，以及一些将它们添加到 SOAPMessage 对象的方法。收到 SOAPMessage 对象的一方可以通过检索各个附件部分来检查消息内容。

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

MessageFactory 对象可以创建行为特定于具体 SAAJ 实现或应用程序的 SOAPMessage 对象。例如，MessageFactory 对象可以生成符合特定配置文件（如 ebXML）的 SOAPMessage 对象。在这种情况下，MessageFactory 对象可以生成使用 ebXML 头初始化的 SOAPMessage 对象。

为了确保与后向源的兼容性，在 SAAJ 规范的 1.1 版本之后添加到此类的方法都是具体而非抽象的，它们都具有默认实现。除在 JavaDocs 中有对这些方法的另行说明外，默认实现只是抛出 UnsupportedOperationException，并且 SAAJ 实现代码必须使用提供指定行为的方法重写它们。但是，只要没有声明符合初始版本之后的某些更高版本规范，遗留客户端代码就没有这种限制。可以根据 SAAJ API 的未修改后续版本来编译和/或运行扩展 SOAPMessage 类的遗留类。如果正确实现了这样的类，则对于规范的更高版本（相对于初始版本）来说，该类将继续有效。

另请参见：

MessageFactory, AttachmentPart

CHARACTER_SET_ENCODING

public static final String CHARACTER_SET_ENCODING

指定 SOAP Message 的字符类型编码。有效值包括 "utf-8" 和 "utf-16"。有关其他受支持的值，请参阅供应商文档。默认值是 "utf-8"。

从以下版本开始：

SAAJ 1.2

另请参见：

SOAPMessage.setProperty, 常量字段值

WRITE_XML_DECLARATION

public static final String WRITE_XML_DECLARATION

指定 SOAP Message 在发送时是否包含 XML 声明。仅有的有效值为 "true" 和 "false"。默认值为 "false"。

从以下版本开始：

SAAJ 1.2

另请参见：

SOAPMessage.setProperty, 常量字段值

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 正文部分。

返回：

此 SOAPMessage 对象的 SOAPPart 对象

getSOAPBody

public SOAPBody getSOAPBody()
                     throws SOAPException

获取此 SOAPMessage 对象中包含的 SOAP Body。

返回：

此 SOAPMessage 对象包含的 SOAPBody 对象

抛出：

SOAPException - 如果 SOAP Body 不存在或无法被检索

从以下版本开始：

SAAJ 1.2

getSOAPHeader

public SOAPHeader getSOAPHeader()
                         throws SOAPException

获取此 SOAPMessage 对象中包含的 SOAP Header。

返回：

此 SOAPMessage 对象包含的 SOAPHeader 对象

抛出：

SOAPException - 如果 SOAP Header 不存在或无法被检索

从以下版本开始：

SAAJ 1.2

removeAllAttachments

public abstract void removeAllAttachments()

移除所有已经添加到此 SOAPMessage 对象的 AttachmentPart 对象。

此方法不接触 SOAP 部分。

countAttachments

public abstract int countAttachments()

获取此消息中附件数量的计数。此计数不包括 SOAP 部分。

返回：

作为此 SOAPMessage 对象一部分的 AttachmentPart 对象的数量

getAttachments

public abstract Iterator getAttachments()

检索所有作为此 SOAPMessage 对象一部分的 AttachmentPart 对象。

返回：

可在此消息中所有附件上进行迭代的迭代器。

getAttachments

public abstract Iterator getAttachments(MimeHeaders headers)

检索所有头条目匹配指定头的 AttachmentPart 对象。注意，返回的附件除指定的头之外，还可以有其他头。

参数：

headers - 包含要搜索的 MIME 头的 MimeHeaders 对象

返回：

一个迭代器，可在所有头匹配任一给定头的附件上进行迭代

removeAttachments

public abstract void removeAttachments(MimeHeaders headers)

移除所有头条目匹配指定头的 AttachmentPart 对象。注意，移除的附件除指定的头之外，还可以有其他头。

参数：

headers - 包含要搜索的 MIME 头的 MimeHeaders 对象

从以下版本开始：

SAAJ 1.3

getAttachment

public abstract AttachmentPart getAttachment(SOAPElement element)
                                      throws SOAPException

返回与此 SOAPElement 引用的附件关联的 AttachmentPart 对象，如果不存在此类附件，则返回 null。可以通过 SOAP Messages with Attachments 中描述的 href 属性，或者包含 WS-I Attachments Profile 1.0（用于模式类型 ref:swaRef( ref:swaRef) 的元素）中所描述的 URI 的一个 Text 子节点来进行引用。必须支持这两种机制。支持通过 href 属性获取引用同时意味着，对于作为 xop:Include 元素 ( XOP) 的元素也应该支持此方法。其他引用机制可以由此标准的各个实现支持。有关详细信息，请与您的供应商联系。

参数：

element - 包含对附件引用的 SOAPElement

返回：

引用的 AttachmentPart；如果不存在此类 AttachmentPart 或在此 SOAPElement 中找不到引用，则返回 null。

抛出：

SOAPException - 如果尝试访问附件时出现错误

从以下版本开始：

SAAJ 1.3

addAttachmentPart

public abstract void addAttachmentPart(AttachmentPart AttachmentPart)

将给定的 AttachmentPart 对象添加到此 SOAPMessage 对象。必须先创建 AttachmentPart 对象，然后才能将其添加到消息。

参数：

AttachmentPart - 将作为此 SOAPMessage 对象一部分的 AttachmentPart 对象

抛出：

IllegalArgumentException

createAttachmentPart

public abstract AttachmentPart createAttachmentPart()

创建一个新的空 AttachmentPart 对象。注意，调用方法 addAttachmentPart 时必须将此新 AttachmentPart 对象作为参数，以便该对象成为此 SOAPMessage 对象的附件。

返回：

可以填充并添加到此 SOAPMessage 对象的新的 AttachmentPart 对象

createAttachmentPart

public AttachmentPart createAttachmentPart(DataHandler dataHandler)

创建 AttachmentPart 对象并使用给定的 DataHandler 对象填充。

参数：

dataHandler - 将生成此 SOAPMessage 对象内容的 javax.activation.DataHandler 对象

返回：

包含给定 DataHandler 对象生成数据的新的 AttachmentPart 对象

抛出：

IllegalArgumentException - 如果指定的 DataHandler 对象存在问题

另请参见：

DataHandler, DataContentHandler

getMimeHeaders

public abstract MimeHeaders getMimeHeaders()

以与传输无关的方式返回此 SOAPMessage 对象所有特定于传输的 MIME 头。

返回：

包含 MimeHeader 对象的 MimeHeaders 对象

createAttachmentPart

public AttachmentPart createAttachmentPart(Object content,
                                           String contentType)

创建 AttachmentPart 对象并使用指定内容类型的指定数据填充。 Object 的类型应该对应于指定给 Content-Type 的值。

参数：

content - 包含要创建的 AttachmentPart 对象内容的 Object

contentType - 给出内容类型的 String 对象；例如 "text/xml"、"text/plain" 和 "image/jpeg"

返回：

包含给定数据的新的 AttachmentPart 对象

抛出：

IllegalArgumentException - 如果 contentType 不匹配内容对象的类型，或者没有给定内容对象的 DataContentHandler 对象时抛出

另请参见：

DataHandler, DataContentHandler

saveChanges

public abstract void saveChanges()
                          throws SOAPException

使用对其所作的所有更改更新此 SOAPMessage 对象。调用 writeTo(OutputStream) 时自动调用此方法。但是，如果是对已收到或已发送的消息进行更改，则需要显式调用方法 saveChanges 保存这些更改。方法 saveChanges 还生成任何可以回读的更改（例如，支持消息 id 的配置文件中 MessageId）。只有在调用 saveChanges 之后，才能保证为发送而创建的消息中的所有 MIME 头具有有效值。

此外，此方法标记了位置点，取自所有 AttachmentPart 对象组件的数据在该点处被拉入消息。

抛出：

SOAPException - 如果在保存此消息的更改时出现问题。

SOAPException

saveRequired

public abstract boolean saveRequired()

指示是否此 SOAPMessage 对象需要调用方法 saveChanges。

返回：

如果需要调用 saveChanges，则返回 true；否则返回 false。

writeTo

public abstract void writeTo(OutputStream out)
                      throws SOAPException,
                             IOException

将此 SOAPMessage 对象写入给定输出流。具体化格式在 SOAP 1.1 with Attachments 规范中定义。

如果没有附件，则只写出 XML 流。对于有附件的消息，writeTo 写出 MIME 编码的字节流。

注意，此方法不写出特定于传输的消息的 MIME Header

参数：

out - SOAPMessage 对象将写入的 OutputStream 对象

抛出：

IOException - 如果发生 I/O 错误

SOAPException - 在具体化此 SOAP 消息时出现问题

setProperty

public void setProperty(String property,
                        Object value)
                 throws SOAPException

将指定值与指定属性关联。如果已经有与此属性关联的值，则替换旧值。

有效属性名包括 WRITE_XML_DECLARATION 和 CHARACTER_SET_ENCODING。所有这些标准 SAAJ 属性都以 "javax.xml.soap" 为前缀。供应商也可以添加特定于实现的属性。这些属性必须以供应商所独有的包名称为前缀。

将属性 WRITE_XML_DECLARATION 设置为 "true" 会导致在 SOAP 消息的起始处写出 XML Declaration。默认值 "false" 表示取消此声明。

属性 CHARACTER_SET_ENCODING 默认为值 "utf-8"，该值将导致使用 UTF-8 编码 SOAP 消息。将 CHARACTER_SET_ENCODING 设置为 "utf-16" 将导致使用 UTF-16 编码 SOAP 消息。

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

参数：

property - 要关联指定值的属性。

value - 要与指定属性关联的值

抛出：

SOAPException - 如果无法识别属性名。

从以下版本开始：

SAAJ 1.2

getProperty

public Object getProperty(String property)
                   throws SOAPException

检索指定属性的值。

参数：

property - 要检索的属性名称

返回：

与指定属性关联的值；如果不存在此类属性，则返回 null。

抛出：

SOAPException - 如果无法识别属性名。

从以下版本开始：

SAAJ 1.2