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

Constructors
Constructor and Description
`MessageFactory()`

### Method Summary

Methods
`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.

Copyright © 1993, 2017, Oracle and/or its affiliates. All rights reserved.