SOAPMessage (Java EE 5)

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

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

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

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

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

可以通过调用方法 SOAPMessage.getSOAPPart() 检索消息的 SOAP 部分。SOAPEnvelope 对象是从 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 类的遗留类。如果正确实现了这样的类，则对于规范的更高版本（相对于初始版本）来说，该类将继续有效。

See also

javax.xml.soap.MessageFactory, javax.xml.soap.AttachmentPart

英文文档：

The root class for all SOAP messages. As transmitted on the "wire", a SOAP message is an XML document or a MIME message whose first body part is an XML/SOAP document.

A SOAPMessage object consists of a SOAP part and optionally one or more attachment parts. The SOAP part for a SOAPMessage object is a SOAPPart object, which contains information used for message routing and identification, and which can contain application-specific content. All data in the SOAP Part of a message must be in XML format.

A new SOAPMessage object contains the following by default:

• A SOAPPart object
• A SOAPEnvelope object
• A SOAPBody object
• A SOAPHeader object

The SOAP part of a message can be retrieved by calling the method SOAPMessage.getSOAPPart(). The SOAPEnvelope object is retrieved from the SOAPPart object, and the SOAPEnvelope object is used to retrieve the SOAPBody and SOAPHeader objects.

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

In addition to the mandatory SOAPPart object, a SOAPMessage object may contain zero or more AttachmentPart objects, each of which contains application-specific data. The SOAPMessage interface provides methods for creating AttachmentPart objects and also for adding them to a SOAPMessage object. A party that has received a SOAPMessage object can examine its contents by retrieving individual attachment parts.

Unlike the rest of a SOAP message, an attachment is not required to be in XML format and can therefore be anything from simple text to an image file. Consequently, any message content that is not in XML format must be in an AttachmentPart object.

A MessageFactory object may create SOAPMessage objects with behavior that is specialized to a particular implementation or application of SAAJ. For instance, a MessageFactory object may produce SOAPMessage objects that conform to a particular Profile such as ebXML. In this case a MessageFactory object might produce SOAPMessage objects that are initialized with ebXML headers.

In order to ensure backward source compatibility, methods that are added to this class after version 1.1 of the SAAJ specification are all concrete instead of abstract and they all have default implementations. Unless otherwise noted in the JavaDocs for those methods the default implementations simply throw an UnsupportedOperationException and the SAAJ implementation code must override them with methods that provide the specified behavior. Legacy client code does not have this restriction, however, so long as there is no claim made that it conforms to some later version of the specification than it was originally written for. A legacy class that extends the SOAPMessage class can be compiled and/or run against succeeding versions of the SAAJ API without modification. If such a class was correctly implemented then it will continue to behave correctly relative to the version of the specification against which it was written.

See Also:

MessageFactory, AttachmentPart

---

Field Summary
static String	CHARACTER_SET_ENCODING           Specifies the character type encoding for the SOAP Message.
static String	WRITE_XML_DECLARATION           Specifies whether the SOAP Message will contain an XML declaration when it is sent.

 

Constructor Summary
SOAPMessage()

 

Method Summary
abstract  void	addAttachmentPart(AttachmentPart AttachmentPart)           Adds the given AttachmentPart object to this SOAPMessage object.
abstract  int	countAttachments()           Gets a count of the number of attachments in this message.
abstract  AttachmentPart	createAttachmentPart()           Creates a new empty AttachmentPart object.
AttachmentPart	createAttachmentPart(DataHandler dataHandler)           Creates an AttachmentPart object and populates it using the given DataHandler object.
AttachmentPart	createAttachmentPart(Object content, String contentType)           Creates an AttachmentPart object and populates it with the specified data of the specified content type.
abstract  AttachmentPart	getAttachment(SOAPElement element)           Returns an AttachmentPart object that is associated with an attachment that is referenced by this SOAPElement or null if no such attachment exists.
abstract  Iterator	getAttachments()           Retrieves all the AttachmentPart objects that are part of this SOAPMessage object.
abstract  Iterator	getAttachments(MimeHeaders headers)           Retrieves all the AttachmentPart objects that have header entries that match the specified headers.
abstract  String	getContentDescription()           Retrieves a description of this SOAPMessage object's content.
abstract  MimeHeaders	getMimeHeaders()           Returns all the transport-specific MIME headers for this SOAPMessage object in a transport-independent fashion.
Object	getProperty(String property)           Retrieves value of the specified property.
SOAPBody	getSOAPBody()           Gets the SOAP Body contained in this SOAPMessage object.
SOAPHeader	getSOAPHeader()           Gets the SOAP Header contained in this SOAPMessage object.
abstract  SOAPPart	getSOAPPart()           Gets the SOAP part of this SOAPMessage object.
abstract  void	removeAllAttachments()           Removes all AttachmentPart objects that have been added to this SOAPMessage object.
abstract  void	removeAttachments(MimeHeaders headers)           Removes all the AttachmentPart objects that have header entries that match the specified headers.
abstract  void	saveChanges()           Updates this SOAPMessage object with all the changes that have been made to it.
abstract  boolean	saveRequired()           Indicates whether this SOAPMessage object needs to have the method saveChanges called on it.
abstract  void	setContentDescription(String description)           Sets the description of this SOAPMessage object's content with the given description.
void	setProperty(String property, Object value)           Associates the specified value with the specified property.
abstract  void	writeTo(OutputStream out)           Writes this SOAPMessage object to the given output stream.

 

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

 

Field Detail

英文文档：

CHARACTER_SET_ENCODING

public static final String CHARACTER_SET_ENCODING

Specifies the character type encoding for the SOAP Message. Valid values include "utf-8" and "utf-16". See vendor documentation for additional supported values. The default is "utf-8".

Since:

SAAJ 1.2

See Also:

SOAPMessage.setProperty, Constant Field Values

---

英文文档：

WRITE_XML_DECLARATION

public static final String WRITE_XML_DECLARATION

Specifies whether the SOAP Message will contain an XML declaration when it is sent. The only valid values are "true" and "false". The default is "false".

Since:

SAAJ 1.2

See Also:

SOAPMessage.setProperty, Constant Field Values

Constructor Detail

public SOAPMessage()

英文文档：

SOAPMessage

public SOAPMessage()

Method Detail

英文文档：

setContentDescription

public abstract void setContentDescription(String description)

Sets the description of this SOAPMessage object's content with the given description.

Parameters:

description - a String describing the content of this message

See Also:

getContentDescription()

---

英文文档：

getContentDescription

public abstract String getContentDescription()

Retrieves a description of this SOAPMessage object's content.

Returns:

a String describing the content of this message or null if no description has been set

See Also:

setContentDescription(java.lang.String)

---

英文文档：

getSOAPPart

public abstract SOAPPart getSOAPPart()

Gets the SOAP part of this SOAPMessage object.

SOAPMessage object contains one or more attachments, the SOAP Part must be the first MIME body part in the message.

Returns:

the SOAPPart object for this SOAPMessage object

---

英文文档：

getSOAPBody

public SOAPBody getSOAPBody()
                     throws SOAPException

Gets the SOAP Body contained in this SOAPMessage object.

Returns:

the SOAPBody object contained by this SOAPMessage object

Throws:

SOAPException - if the SOAP Body does not exist or cannot be retrieved

Since:

SAAJ 1.2

---

英文文档：

getSOAPHeader

public SOAPHeader getSOAPHeader()
                         throws SOAPException

Gets the SOAP Header contained in this SOAPMessage object.

Returns:

the SOAPHeader object contained by this SOAPMessage object

Throws:

SOAPException - if the SOAP Header does not exist or cannot be retrieved

Since:

SAAJ 1.2

---

abstract public void removeAllAttachments()
移除所有已经添加到此 SOAPMessage 对象的 AttachmentPart 对象。

此方法不接触 SOAP 部分。

英文文档：

removeAllAttachments

public abstract void removeAllAttachments()

Removes all AttachmentPart objects that have been added to this SOAPMessage object.

This method does not touch the SOAP part.

---

abstract public int countAttachments()
获取此消息中附件数量的计数。此计数不包括 SOAP 部分。

return

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

英文文档：

countAttachments

public abstract int countAttachments()

Gets a count of the number of attachments in this message. This count does not include the SOAP part.

Returns:

the number of AttachmentPart objects that are part of this SOAPMessage object

---

英文文档：

getAttachments

public abstract Iterator getAttachments()

Retrieves all the AttachmentPart objects that are part of this SOAPMessage object.

Returns:

an iterator over all the attachments in this message

---

英文文档：

getAttachments

public abstract Iterator getAttachments(MimeHeaders headers)

Retrieves all the AttachmentPart objects that have header entries that match the specified headers. Note that a returned attachment could have headers in addition to those specified.

Parameters:

headers - a MimeHeaders object containing the MIME headers for which to search

Returns:

an iterator over all attachments that have a header that matches one of the given headers

---

abstract public void removeAttachments(MimeHeaders headers)
移除所有头条目匹配指定头的 AttachmentPart 对象。注意，移除的附件除指定的头之外，还可以有其他头。

headers	包含要搜索的 MIME 头的 MimeHeaders 对象
since	SAAJ 1.3

英文文档：

removeAttachments

public abstract void removeAttachments(MimeHeaders headers)

Removes all the AttachmentPart objects that have header entries that match the specified headers. Note that the removed attachment could have headers in addition to those specified.

Parameters:

headers - a MimeHeaders object containing the MIME headers for which to search

Since:

SAAJ 1.3

---

abstract public AttachmentPart getAttachment(SOAPElement element) throws SOAPException
返回与此 SOAPElement 引用的附件关联的 AttachmentPart 对象，如果不存在此类附件，则返回 null。可以通过 java.lang.NullPointerException at com.sun.tools.javadoc.DocEnv.getClassSymbol(DocEnv.java:177) at com.sun.tools.javadoc.DocEnv.lookupClass(DocEnv.java:133) at com.sun.tools.javadoc.ClassDocImpl.searchClass(ClassDocImpl.java:682) at com.sun.tools.javadoc.ClassDocImpl.findClass(ClassDocImpl.java:665) at com.sun.tools.docserver.DocServlet.writeSeeTagDoc(DocServlet.java:900) at com.sun.tools.docserver.DocServlet.writeInlineTagString(DocServlet.java:989) at com.sun.tools.docserver.DocServlet.writeTagPara(DocServlet.java:614) at com.sun.tools.docserver.DocServlet.writeDoc(DocServlet.java:523) at com.sun.tools.docserver.DocServlet.writeMethodTable(DocServlet.java:877) at com.sun.tools.docserver.DocServlet.processRequest(DocServlet.java:229) at com.sun.tools.docserver.DocServlet.doGet(DocServlet.java:744) at javax.servlet.http.HttpServlet.service(HttpServlet.java:718) at javax.servlet.http.HttpServlet.service(HttpServlet.java:831) at org.apache.catalina.core.ApplicationFilterChain.servletService(ApplicationFilterChain.java:411) at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:290) at org.apache.catalina.core.StandardContextValve.invokeInternal(StandardContextValve.java:271) at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:202) at org.apache.catalina.core.StandardPipeline.doInvoke(StandardPipeline.java:624) at org.apache.catalina.core.StandardPipeline.doInvoke(StandardPipeline.java:577) at com.sun.enterprise.web.WebPipeline.invoke(WebPipeline.java:94) at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:206) at org.apache.catalina.core.StandardPipeline.doInvoke(StandardPipeline.java:624) at org.apache.catalina.core.StandardPipeline.doInvoke(StandardPipeline.java:577) at org.apache.catalina.core.StandardPipeline.invoke(StandardPipeline.java:571) at org.apache.catalina.core.ContainerBase.invoke(ContainerBase.java:1080) at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:150) at org.apache.catalina.core.StandardPipeline.doInvoke(StandardPipeline.java:624) at org.apache.catalina.core.StandardPipeline.doInvoke(StandardPipeline.java:577) at org.apache.catalina.core.StandardPipeline.invoke(StandardPipeline.java:571) at org.apache.catalina.core.ContainerBase.invoke(ContainerBase.java:1080) at org.apache.coyote.tomcat5.CoyoteAdapter.service(CoyoteAdapter.java:268) at com.sun.enterprise.web.connector.grizzly.DefaultProcessorTask.invokeAdapter(DefaultProcessorTask.java:631) at com.sun.enterprise.web.connector.grizzly.DefaultProcessorTask.doProcess(DefaultProcessorTask.java:562) at com.sun.enterprise.web.connector.grizzly.DefaultProcessorTask.process(DefaultProcessorTask.java:803) at com.sun.enterprise.web.connector.grizzly.DefaultReadTask.executeProcessorTask(DefaultReadTask.java:339) at com.sun.enterprise.web.connector.grizzly.DefaultReadTask.doTask(DefaultReadTask.java:261) at com.sun.enterprise.web.connector.grizzly.DefaultReadTask.doTask(DefaultReadTask.java:212) at com.sun.enterprise.web.connector.grizzly.TaskBase.run(TaskBase.java:265) at com.sun.enterprise.web.connector.grizzly.ssl.SSLWorkerThread.run(SSLWorkerThread.java:106)

About DocWeb · Bundles · Export · Export All

Top 10 · Statistics · Login

About Sun · Contact · Privacy · Terms of Use · Trademarks

Java EE 5 SDK · Copyright © 1994-2008 Sun Microsystems, Inc.

public abstract AttachmentPart getAttachment(SOAPElement element)
                                      throws SOAPException

public abstract void addAttachmentPart(AttachmentPart AttachmentPart)

public abstract AttachmentPart createAttachmentPart()

public AttachmentPart createAttachmentPart(DataHandler dataHandler)

public abstract MimeHeaders getMimeHeaders()

public AttachmentPart createAttachmentPart(Object content,
                                           String contentType)

public abstract void saveChanges()
                          throws SOAPException

public abstract boolean saveRequired()

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

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

public Object getProperty(String property)
                   throws SOAPException