MessageFactory (Java EE 5)

Java EE API

previous page next page
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap Class MessageFactory

java.lang.Object
  extended by javax.xml.soap.MessageFactory

public abstract class MessageFactory
extends Object


创建 SOAPMessage 对象的工厂。

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

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

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

  • 一个 SOAPPart 对象
  • 一个 SOAPEnvelope 对象
  • 一个 SOAPBody 对象
  • 一个 SOAPHeader 对象
在某些情况下，可以获取特殊的 MessageFactory 对象来生成用 SOAPHeader 对象和 SOAPBody 对象中的附加条目预填充的消息。新的 SOAPMessage 对象的内容取决于使用两种 MessageFactory 方法中的哪一种创建该对象。
  • 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
In some cases, specialized MessageFactory objects may be obtained that produce messages prepopulated with additional entries in the SOAPHeader object and the SOAPBody object. The content of a new SOAPMessage object depends on which of the two MessageFactory methods is used to create it.
  • 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.

Constructor Summary
MessageFactory()
           
 
Method Summary
abstract  SOAPMessage createMessage()
          Creates a new SOAPMessage object with the default SOAPPart, SOAPEnvelope, SOAPBody, and SOAPHeader objects.
abstract  SOAPMessage createMessage(MimeHeaders headers, InputStream in)
          Internalizes the contents of the given InputStream object into a new SOAPMessage object and returns the SOAPMessage object.
static MessageFactory newInstance()
          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.
static MessageFactory newInstance(String protocol)
          Creates a new MessageFactory object that is an instance of the specified implementation.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

public MessageFactory()
英文文档：

MessageFactory

public MessageFactory()
Method Detail

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 实例
ThrowsSOAPException: 如果创建默认的 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。
ThrowsSOAPException: 如果创建指定的 MessageFactory 实例时存在错误。
sinceSAAJ 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 对象
ThrowsSOAPException: 如果发生 SOAP 错误
ThrowsUnsupportedOperationException: 如果此 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 对象的数据
Throwsjava.io.IOException: 如果读取输入流的数据时存在错误
ThrowsSOAPException: 消息无效时抛出
ThrowsIllegalArgumentException: 如果 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.
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature

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

一看就知道只有菜鸟才干这么无知的事啦。

PS : 未经我党受权你也可自由散发此文档。 如有任何错误请自行修正；若因此而造成任何损失请直接找人民主席，请勿与本人联系。谢谢！

previous page start next page