public abstract class MessageFactory {
// Public Constructors
public MessageFactory( );
// Public Class Methods
public static MessageFactory newInstance( ) throws SOAPException;
// Public Instance Methods
public abstract SOAPMessage createMessage( ) throws SOAPException;
public abstract SOAPMessage createMessage(MimeHeaders headers,
java.io.InputStream in) throws java.io.IOExceptionSOAPException;
}
MessageFactory is an abstract base class that
provides the methods used by application code to construct SOAP
messages. A SAAJ application obtains an instance of this class by
calling the static newInstance( ) method, which
looks for a suitable concrete implementation using the following
algorithm:
Looks in the system properties for a property called
javax.xml.soap.MessageFactory. If this property is
defined, its value is assumed to be the class name of a concrete
implementation of MessageFactory.
Looks for the same property in a file called
${JAVA_HOME}/lib/jaxm.properties. If the
property is found, its value is assumed to be the required class
name.
Looks for a resource called
META-INF/services/javax.xml.soap.MessageFactory in
the classpath. If such a resource exists, it is opened and a single
line is read from it. If the line is not empty, it is used as the
class name.
Finally, an implementation-dependent default class is used. In the
case of the reference implementation, this class is called
com.sun.xml.messaging.saaj.soap.MessageFactoryImpl.
Once you have a MessageFactory, use its
zero-argument createMessage( ) method to obtain a
basic SOAPMessage object to which you can then add
content and attachments. The default
MessageFactory provided by the SAAJ reference
implementation returns a message that contains the following:
A SOAPEnvelope within a
SOAPPart object
An empty SOAPHeader, followed by an empty
SOAPBody, inside the
SOAPEnvelope
Since the MessageFactory is found using a lookup
process, it is possible to plug in a custom factory that will return
a SOAPMessage that is partially populated with
elements that a particular application or suite of applications might
require, without modifying application code.
The other variant of createMessage( ) is intended
to be used to deserialize a SOAP message
received from an HTTP connection or some other communications
mechanism into a SOAPMessage object and therefore
is most commonly used by servlets. The in argument
provides an InputStream from which the raw XML
message can be read, while the headers argument is
a MimeHeaders object containing the MIME headers
that accompanied the message and therefore accessible from the
SOAPPart object within the resulting
SOAPMessage. Refer to Chapter 6
for an example that shows how to use this method to handle a SOAP
message from within a servlet.
