MessageFactory (Java EE 5)

SAAJ 客户端可以使用方法 newInstance 创建 MessageFactory 对象，如以下代码行所示。

MessageFactory mf = MessageFactory.newInstance();
MessageFactory mf12 = MessageFactory.newInstance(SOAPConstants.SOAP_1_2_PROTOCOL);
 

默认情况下，所有 MessageFactory 对象（无论它们是如何创建的）都将生成具有以下元素的 SOAPMessage 对象：

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

• createMessage()
  这是客户端通常用来创建请求消息的方法。
• createMessage(MimeHeaders, java.io.InputStream) -- 消息的内容取自 InputStream 对象，头取自 MimeHeaders 对象。
  此方法可以供服务实现在内部用来创建响应请求的消息。

A factory for creating SOAPMessage objects.

A SAAJ client can create a MessageFactory object using the method newInstance, as shown in the following lines of code.

       MessageFactory mf = MessageFactory.newInstance();
       MessageFactory mf12 = MessageFactory.newInstance(SOAPConstants.SOAP_1_2_PROTOCOL);
 

All MessageFactory objects, regardless of how they are created, will produce SOAPMessage objects that have the following elements by default:

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

• createMessage()
  This is the method clients would normally use to create a request message.
• createMessage(MimeHeaders, java.io.InputStream) -- message has content from the InputStream object and headers from the MimeHeaders object
  This method can be used internally by a service implementation to create a message that is a response to a request.

public MessageFactory()

英文文档：

MessageFactory

public MessageFactory()

public static MessageFactory newInstance() throws SOAPException
创建新的 MessageFactory 对象，该对象是默认实现 (SOAP 1.1) 的实例。 此方法使用以下查找过程顺序来确定要加载的 MessageFactory 实现类：

• 使用 javax.xml.soap.MessageFactory 系统属性。
• 使用 JRE 文件夹中的属性文件 "lib/jaxm.properties"。此配置文件格式是标准的 java.util.Properties 格式且包含实现类的完全限定名，其中实现类的键是上文定义的系统属性。
• 如果 Services API（在 JAR 规范中进行了详细描述）可用，可以使用它来确定类名称。Services API 将查找在运行时可用的 jar 中 META-INF/services/javax.xml.soap.MessageFactory 文件中的类名称。
• 使用 SAAJMetaFactory 实例来定位 MessageFactory 实现类。

return	新的 MessageFactory 实例
Throws	SOAPException: 如果创建默认的 MessageFactory 实现时存在错误。
See also	javax.xml.soap.SAAJMetaFactory

英文文档：

newInstance

public static MessageFactory newInstance()
                                  throws SOAPException

Creates a new MessageFactory object that is an instance of the default implementation (SOAP 1.1), This method uses the following ordered lookup procedure to determine the MessageFactory implementation class to load:

• Use the javax.xml.soap.MessageFactory system property.
• Use the properties file "lib/jaxm.properties" in the JRE directory. This configuration file is in standard java.util.Properties format and contains the fully qualified name of the implementation class with the key being the system property defined above.
• Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API will look for a classname in the file META-INF/services/javax.xml.soap.MessageFactory in jars available to the runtime.
• Use the SAAJMetaFactory instance to locate the MessageFactory implementation class.

Returns:

a new instance of a MessageFactory

Throws:

SOAPException - if there was an error in creating the default implementation of the MessageFactory.

See Also:

SAAJMetaFactory

public static MessageFactory newInstance(String protocol) throws SOAPException
创建新的 MessageFactory 对象，该对象是指定实现的实例。可以是动态消息工厂、SOAP 1.1 消息工厂或 SOAP 1.2 消息工厂。动态消息工厂根据作为 createMessage 方法参数指定的 MIME 头创建消息。此方法使用 SAAJMetaFactory 来定位实现类并创建 MessageFactory 实例。

return	新的 MessageFactory 实例
protocol	字符串常量，表示指定消息工厂实现的类。可以是 DYNAMIC_SOAP_PROTOCOL、DEFAULT_SOAP_PROTOCOL（等同于 SOAP_1_1_PROTOCOL）或 SOAP_1_2_PROTOCOL。
Throws	SOAPException: 如果创建指定的 MessageFactory 实例时存在错误。
since	SAAJ 1.3
See also	javax.xml.soap.SAAJMetaFactory

英文文档：

newInstance

public static MessageFactory newInstance(String protocol)
                                  throws SOAPException

Creates a new MessageFactory object that is an instance of the specified implementation. May be a dynamic message factory, a SOAP 1.1 message factory, or a SOAP 1.2 message factory. A dynamic message factory creates messages based on the MIME headers specified as arguments to the createMessage method. This method uses the SAAJMetaFactory to locate the implementation class and create the MessageFactory instance.

Parameters:

protocol - a string constant representing the class of the specified message factory implementation. May be either DYNAMIC_SOAP_PROTOCOL, DEFAULT_SOAP_PROTOCOL (which is the same as) SOAP_1_1_PROTOCOL, or SOAP_1_2_PROTOCOL.

Returns:

a new instance of a MessageFactory

Throws:

SOAPException - if there was an error in creating the specified implementation of MessageFactory.

Since:

SAAJ 1.3

See Also:

SAAJMetaFactory

abstract public SOAPMessage createMessage() throws SOAPException
使用默认的 SOAPPart、SOAPEnvelope、SOAPBody 和 SOAPHeader 对象创建新的 SOAPMessage 对象。特定于配置文件的消息工厂可以选择用特定于配置文件的头预填充 SOAPMessage 对象。

可以向此消息的 SOAPPart 对象添加内容，如果一个只包含 SOAP 部分的消息便已足够，则可以按“原样”发送消息。否则，SOAPMessage 对象需要创建一个或多个 AttachmentPart 对象并将其添加到自身。任何非 XML 格式的内容必须在 AttachmentPart 对象中。

return	一个新的 SOAPMessage 对象
Throws	SOAPException: 如果发生 SOAP 错误
Throws	UnsupportedOperationException: 如果此 MessageFactory 实例的协议是 DYNAMIC_SOAP_PROTOCOL

英文文档：

createMessage

public abstract SOAPMessage createMessage()
                                   throws SOAPException

Creates a new SOAPMessage object with the default SOAPPart, SOAPEnvelope, SOAPBody, and SOAPHeader objects. Profile-specific message factories can choose to prepopulate the SOAPMessage object with profile-specific headers.

Content can be added to this message's SOAPPart object, and the message can be sent "as is" when a message containing only a SOAP part is sufficient. Otherwise, the SOAPMessage object needs to create one or more AttachmentPart objects and add them to itself. Any content that is not in XML format must be in an AttachmentPart object.

Returns:

a new SOAPMessage object

Throws:

SOAPException - if a SOAP error occurs

UnsupportedOperationException - if the protocol of this MessageFactory instance is DYNAMIC_SOAP_PROTOCOL

abstract public SOAPMessage createMessage(MimeHeaders headers, java.io.InputStream in) throws java.io.IOException, SOAPException
将给定 InputStream 对象的内容内部化到新的 SOAPMessage 对象，并返回该 SOAPMessage 对象。

in	包含消息数据的 InputStream 对象
headers	用于创建消息的特定于传输的头，使用与传输无关的方式传递给消息
return	一个新的 SOAPMessage 对象，包含给定 InputStream 对象的数据
Throws	java.io.IOException: 如果读取输入流的数据时存在错误
Throws	SOAPException: 消息无效时抛出
Throws	IllegalArgumentException: 如果 MessageFactory 需要一个或多个 MIME 头存在于 headers 参数中，但是它们丢失了。SOAP_1_1_PROTOCOL 或 SOAP_1_2_PROTOCOL 的 MessageFactory 实现不得因此抛出 IllegalArgumentException。

英文文档：

createMessage

public abstract SOAPMessage createMessage(MimeHeaders headers,
                                          InputStream in)
                                   throws IOException,
                                          SOAPException

Internalizes the contents of the given InputStream object into a new SOAPMessage object and returns the SOAPMessage object.

Parameters:

in - the InputStream object that contains the data for a message

headers - the transport-specific headers passed to the message in a transport-independent fashion for creation of the message

Returns:

a new SOAPMessage object containing the data from the given InputStream object

Throws:

IOException - if there is a problem in reading data from the input stream

SOAPException - may be thrown if the message is invalid

IllegalArgumentException - if the MessageFactory requires one or more MIME headers to be present in the headers parameter and they are missing. MessageFactory implementations for SOAP_1_1_PROTOCOL or SOAP_1_2_PROTOCOL must not throw IllegalArgumentException for this reason.

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.