Jakarta SOAP with Attachments API 3.0.0 · jakarta.xml.soap.MessageFactory

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.

Modifier and Type	Field and Description
private static final String	DEFAULT_MESSAGE_FACTORY

Access	Constructor and Description
protected	MessageFactory() Default constructor.

Method Summary

Modifier and Type	Method and Description
public abstract SOAPMessage	Returns: a new `SOAPMessage` object createMessage() Creates a new `SOAPMessage` object with the default `SOAPPart`, `SOAPEnvelope`, `SOAPBody`, and `SOAPHeader` objects.
public abstract SOAPMessage	Returns: a new `SOAPMessage` object containing the data from the given `InputStream` object createMessage(MimeHeaders the transport-specific headers passed to the message in a transport-independent fashion for creation of the message headers, InputStream the `InputStream` object that contains the data for a message in) Internalizes the contents of the given `InputStream` object into a new `SOAPMessage` object and returns the `SOAPMessage` object.
public static MessageFactory	Returns: a new instance of a `MessageFactory` newInstance() Creates a new `MessageFactory` object that is an instance of the default implementation (SOAP 1.1).
public static MessageFactory	Returns: a new instance of a `MessageFactory` newInstance(String 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`. protocol) Creates a new `MessageFactory` object that is an instance of the specified implementation.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

DEFAULT_MESSAGE_FACTORY	back to summary
private static final String DEFAULT_MESSAGE_FACTORY

Constructor Detail

MessageFactory	back to summary
protected MessageFactory() Default constructor.

Method Detail

createMessage back to summary

createMessage	back to summary
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:SOAPMessage a new `SOAPMessage` object Exceptions SOAPException: if a SOAP error occurs UnsupportedOperationException: if the protocol of this `MessageFactory` instance is `DYNAMIC_SOAP_PROTOCOL`

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:SOAPMessage

a new SOAPMessage object

Exceptions

SOAPException:: if a SOAP error occurs
UnsupportedOperationException:: if the protocol of this MessageFactory instance is DYNAMIC_SOAP_PROTOCOL

createMessage back to summary

createMessage	back to summary
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 headers:MimeHeaders the transport-specific headers passed to the message in a transport-independent fashion for creation of the message in:InputStream the `InputStream` object that contains the data for a message Returns:SOAPMessage a new `SOAPMessage` object containing the data from the given `InputStream` object Exceptions 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.

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

headers:MimeHeaders: the transport-specific headers passed to the message in a transport-independent fashion for creation of the message
in:InputStream: the InputStream object that contains the data for a message

Returns:SOAPMessage

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

Exceptions

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.

newInstance back to summary

newInstance	back to summary
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 lookup procedure specified in `jakarta.xml.soap` to locate and load the `jakarta.xml.soap.MessageFactory` class. Returns:MessageFactory a new instance of a `MessageFactory` Exceptions SOAPException: if there was an error in creating the default implementation of the `MessageFactory`. See Also `SAAJMetaFactory`

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 lookup procedure specified in jakarta.xml.soap to locate and load the jakarta.xml.soap.MessageFactory class.

Returns:MessageFactory

a new instance of a MessageFactory

Exceptions

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

See Also

SAAJMetaFactory

newInstance back to summary

newInstance	back to summary
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:String 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:MessageFactory a new instance of a `MessageFactory` Exceptions SOAPException: if there was an error in creating the specified implementation of `MessageFactory`. Since 1.6, SAAJ 1.3 See Also `SAAJMetaFactory`

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:String: 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:MessageFactory

a new instance of a MessageFactory

Exceptions

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

Since

1.6, SAAJ 1.3

See Also

SAAJMetaFactory

public abstract Class MessageFactory

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail