001: /*
002: * $Id: MessageFactory.java,v 1.11 2006/03/30 00:59:38 ofung Exp $
003: * $Revision: 1.11 $
004: * $Date: 2006/03/30 00:59:38 $
005: */
006:
007: /*
008: * The contents of this file are subject to the terms
009: * of the Common Development and Distribution License
010: * (the License). You may not use this file except in
011: * compliance with the License.
012: *
013: * You can obtain a copy of the license at
014: * https://glassfish.dev.java.net/public/CDDLv1.0.html.
015: * See the License for the specific language governing
016: * permissions and limitations under the License.
017: *
018: * When distributing Covered Code, include this CDDL
019: * Header Notice in each file and include the License file
020: * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
021: * If applicable, add the following below the CDDL Header,
022: * with the fields enclosed by brackets [] replaced by
023: * you own identifying information:
024: * "Portions Copyrighted [year] [name of copyright owner]"
025: *
026: * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
027: */
028: package javax.xml.soap;
029:
030: import java.io.IOException;
031: import java.io.InputStream;
032:
033: /**
034: * A factory for creating <code>SOAPMessage</code> objects.
035: * <P>
036: * A SAAJ client can create a <code>MessageFactory</code> object
037: * using the method <code>newInstance</code>, as shown in the following
038: * lines of code.
039: * <PRE>
040: * MessageFactory mf = MessageFactory.newInstance();
041: * MessageFactory mf12 = MessageFactory.newInstance(SOAPConstants.SOAP_1_2_PROTOCOL);
042: * </PRE>
043: * <P>
044: * All <code>MessageFactory</code> objects, regardless of how they are
045: * created, will produce <code>SOAPMessage</code> objects that
046: * have the following elements by default:
047: * <UL>
048: * <LI>A <code>SOAPPart</code> object
049: * <LI>A <code>SOAPEnvelope</code> object
050: * <LI>A <code>SOAPBody</code> object
051: * <LI>A <code>SOAPHeader</code> object
052: * </UL>
053: * In some cases, specialized MessageFactory objects may be obtained that produce messages
054: * prepopulated with additional entries in the <code>SOAPHeader</code> object and the
055: * <code>SOAPBody</code> object.
056: * The content of a new <code>SOAPMessage</code> object depends on which of the two
057: * <code>MessageFactory</code> methods is used to create it.
058: * <UL>
059: * <LI><code>createMessage()</code> <BR>
060: * This is the method clients would normally use to create a request message.
061: * <LI><code>createMessage(MimeHeaders, java.io.InputStream)</code> -- message has
062: * content from the <code>InputStream</code> object and headers from the
063: * <code>MimeHeaders</code> object <BR>
064: * This method can be used internally by a service implementation to
065: * create a message that is a response to a request.
066: * </UL>
067: */
068: public abstract class MessageFactory {
069:
070: static private final String DEFAULT_MESSAGE_FACTORY = "com.sun.xml.messaging.saaj.soap.ver1_1.SOAPMessageFactory1_1Impl";
071:
072: static private final String MESSAGE_FACTORY_PROPERTY = "javax.xml.soap.MessageFactory";
073:
074: /**
075: * Creates a new <code>MessageFactory</code> object that is an instance
076: * of the default implementation (SOAP 1.1),
077: *
078: * This method uses the following ordered lookup procedure to determine the MessageFactory implementation class to load:
079: * <UL>
080: * <LI> Use the javax.xml.soap.MessageFactory system property.
081: * <LI> Use the properties file "lib/jaxm.properties" in the JRE directory. This configuration file is in standard
082: * java.util.Properties format and contains the fully qualified name of the implementation class with the key being the
083: * system property defined above.
084: * <LI> Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API
085: * will look for a classname in the file META-INF/services/javax.xml.soap.MessageFactory in jars available to the runtime.
086: * <LI> Use the SAAJMetaFactory instance to locate the MessageFactory implementation class.
087: * </UL>
088:
089: *
090: * @return a new instance of a <code>MessageFactory</code>
091: *
092: * @exception SOAPException if there was an error in creating the
093: * default implementation of the
094: * <code>MessageFactory</code>.
095: * @see SAAJMetaFactory
096: */
097:
098: public static MessageFactory newInstance() throws SOAPException {
099: try {
100: MessageFactory factory = (MessageFactory) FactoryFinder
101: .find(MESSAGE_FACTORY_PROPERTY);
102:
103: if (factory != null)
104: return factory;
105:
106: return newInstance(SOAPConstants.SOAP_1_1_PROTOCOL);
107: } catch (Exception ex) {
108: throw new SOAPException(
109: "Unable to create message factory for SOAP: "
110: + ex.getMessage());
111: }
112:
113: }
114:
115: /**
116: * Creates a new <code>MessageFactory</code> object that is an instance
117: * of the specified implementation. May be a dynamic message factory,
118: * a SOAP 1.1 message factory, or a SOAP 1.2 message factory. A dynamic
119: * message factory creates messages based on the MIME headers specified
120: * as arguments to the <code>createMessage</code> method.
121: *
122: * This method uses the SAAJMetaFactory to locate the implementation class
123: * and create the MessageFactory instance.
124: *
125: * @return a new instance of a <code>MessageFactory</code>
126: *
127: * @param protocol a string constant representing the class of the
128: * specified message factory implementation. May be
129: * either <code>DYNAMIC_SOAP_PROTOCOL</code>,
130: * <code>DEFAULT_SOAP_PROTOCOL</code> (which is the same
131: * as) <code>SOAP_1_1_PROTOCOL</code>, or
132: * <code>SOAP_1_2_PROTOCOL</code>.
133: *
134: * @exception SOAPException if there was an error in creating the
135: * specified implementation of <code>MessageFactory</code>.
136: * @see SAAJMetaFactory
137: * @since SAAJ 1.3
138: */
139: public static MessageFactory newInstance(String protocol)
140: throws SOAPException {
141: return SAAJMetaFactory.getInstance()
142: .newMessageFactory(protocol);
143: }
144:
145: /**
146: * Creates a new <code>SOAPMessage</code> object with the default
147: * <code>SOAPPart</code>, <code>SOAPEnvelope</code>, <code>SOAPBody</code>,
148: * and <code>SOAPHeader</code> objects. Profile-specific message factories
149: * can choose to prepopulate the <code>SOAPMessage</code> object with
150: * profile-specific headers.
151: * <P>
152: * Content can be added to this message's <code>SOAPPart</code> object, and
153: * the message can be sent "as is" when a message containing only a SOAP part
154: * is sufficient. Otherwise, the <code>SOAPMessage</code> object needs
155: * to create one or more <code>AttachmentPart</code> objects and
156: * add them to itself. Any content that is not in XML format must be
157: * in an <code>AttachmentPart</code> object.
158: *
159: * @return a new <code>SOAPMessage</code> object
160: * @exception SOAPException if a SOAP error occurs
161: * @exception UnsupportedOperationException if the protocol of this
162: * <code>MessageFactory</code> instance is <code>DYNAMIC_SOAP_PROTOCOL</code>
163: */
164: public abstract SOAPMessage createMessage() throws SOAPException;
165:
166: /**
167: * Internalizes the contents of the given <code>InputStream</code> object into a
168: * new <code>SOAPMessage</code> object and returns the <code>SOAPMessage</code>
169: * object.
170: *
171: * @param in the <code>InputStream</code> object that contains the data
172: * for a message
173: * @param headers the transport-specific headers passed to the
174: * message in a transport-independent fashion for creation of the
175: * message
176: * @return a new <code>SOAPMessage</code> object containing the data from
177: * the given <code>InputStream</code> object
178: *
179: * @exception IOException if there is a problem in reading data from
180: * the input stream
181: *
182: * @exception SOAPException may be thrown if the message is invalid
183: *
184: * @exception IllegalArgumentException if the <code>MessageFactory</code>
185: * requires one or more MIME headers to be present in the
186: * <code>headers</code> parameter and they are missing.
187: * <code>MessageFactory</code> implementations for
188: * <code>SOAP_1_1_PROTOCOL</code> or
189: * <code>SOAP_1_2_PROTOCOL</code> must not throw
190: * <code>IllegalArgumentException</code> for this reason.
191: */
192: public abstract SOAPMessage createMessage(MimeHeaders headers,
193: InputStream in) throws IOException, SOAPException;
194: }
|