Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Java™ Platform Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.xml.soap
Class MessageFactory

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

    public abstract class MessageFactory

extends Object

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

### MessageFactory

    public MessageFactory()

Method Detail

### 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`

### 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`

### 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`

### 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 | Use | Tree | Deprecated | Index | Help
| Java™ Platform Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2009 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.