View Javadoc
1   /*
2    * Copyright (c) 2004, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package javax.xml.soap;
27  
28  
29  import java.io.IOException;
30  import java.io.InputStream;
31  
32  /**
33   * A factory for creating <code>SOAPMessage</code> objects.
34   * <P>
35   * A SAAJ client can create a <code>MessageFactory</code> object
36   * using the method <code>newInstance</code>, as shown in the following
37   * lines of code.
38   * <PRE>
39   *       MessageFactory mf = MessageFactory.newInstance();
40   *       MessageFactory mf12 = MessageFactory.newInstance(SOAPConstants.SOAP_1_2_PROTOCOL);
41   * </PRE>
42   * <P>
43   * All <code>MessageFactory</code> objects, regardless of how they are
44   * created, will produce <code>SOAPMessage</code> objects that
45   * have the following elements by default:
46   * <UL>
47   *  <LI>A <code>SOAPPart</code> object
48   *  <LI>A <code>SOAPEnvelope</code> object
49   *  <LI>A <code>SOAPBody</code> object
50   *  <LI>A <code>SOAPHeader</code> object
51   * </UL>
52   * In some cases, specialized MessageFactory objects may be obtained that produce messages
53   * prepopulated with additional entries in the <code>SOAPHeader</code> object and the
54   * <code>SOAPBody</code> object.
55   * The content of a new <code>SOAPMessage</code> object depends on which of the two
56   * <code>MessageFactory</code> methods is used to create it.
57   * <UL>
58   *  <LI><code>createMessage()</code> <BR>
59   *      This is the method clients would normally use to create a request message.
60   *  <LI><code>createMessage(MimeHeaders, java.io.InputStream)</code> -- message has
61   *       content from the <code>InputStream</code> object and headers from the
62   *       <code>MimeHeaders</code> object <BR>
63   *        This method can be used internally by a service implementation to
64   *        create a message that is a response to a request.
65   * </UL>
66   */
67  public abstract class MessageFactory {
68  
69      static final String DEFAULT_MESSAGE_FACTORY
70          = "com.sun.xml.internal.messaging.saaj.soap.ver1_1.SOAPMessageFactory1_1Impl";
71  
72      static private final String MESSAGE_FACTORY_PROPERTY
73          = "javax.xml.soap.MessageFactory";
74  
75      /**
76       * Creates a new <code>MessageFactory</code> object that is an instance
77       * of the default implementation (SOAP 1.1),
78       *
79       * This method uses the following ordered lookup procedure to determine the MessageFactory implementation class to load:
80       * <UL>
81       *  <LI> Use the javax.xml.soap.MessageFactory system property.
82       *  <LI> Use the properties file "lib/jaxm.properties" in the JRE directory. This configuration file is in standard
83       * java.util.Properties format and contains the fully qualified name of the implementation class with the key being the
84       * system property defined above.
85       *  <LI> Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API
86       * will look for a classname in the file META-INF/services/javax.xml.soap.MessageFactory in jars available to the runtime.
87       *  <LI> Use the SAAJMetaFactory instance to locate the MessageFactory implementation class.
88       * </UL>
89  
90       *
91       * @return a new instance of a <code>MessageFactory</code>
92       *
93       * @exception SOAPException if there was an error in creating the
94       *            default implementation of the
95       *            <code>MessageFactory</code>.
96       * @see SAAJMetaFactory
97       */
98  
99      public static MessageFactory newInstance() throws SOAPException {
100 
101 
102         try {
103             MessageFactory factory = (MessageFactory) FactoryFinder.find(
104                     MESSAGE_FACTORY_PROPERTY,
105                     DEFAULT_MESSAGE_FACTORY,
106                     false);
107 
108             if (factory != null) {
109                 return factory;
110             }
111             return newInstance(SOAPConstants.SOAP_1_1_PROTOCOL);
112 
113         } catch (Exception ex) {
114             throw new SOAPException(
115                     "Unable to create message factory for SOAP: "
116                                     +ex.getMessage());
117         }
118 
119     }
120 
121     /**
122      * Creates a new <code>MessageFactory</code> object that is an instance
123      * of the specified implementation.  May be a dynamic message factory,
124      * a SOAP 1.1 message factory, or a SOAP 1.2 message factory. A dynamic
125      * message factory creates messages based on the MIME headers specified
126      * as arguments to the <code>createMessage</code> method.
127      *
128      * This method uses the SAAJMetaFactory to locate the implementation class
129      * and create the MessageFactory instance.
130      *
131      * @return a new instance of a <code>MessageFactory</code>
132      *
133      * @param protocol  a string constant representing the class of the
134      *                   specified message factory implementation. May be
135      *                   either <code>DYNAMIC_SOAP_PROTOCOL</code>,
136      *                   <code>DEFAULT_SOAP_PROTOCOL</code> (which is the same
137      *                   as) <code>SOAP_1_1_PROTOCOL</code>, or
138      *                   <code>SOAP_1_2_PROTOCOL</code>.
139      *
140      * @exception SOAPException if there was an error in creating the
141      *            specified implementation of  <code>MessageFactory</code>.
142      * @see SAAJMetaFactory
143      * @since SAAJ 1.3
144      */
145     public static MessageFactory newInstance(String protocol) throws SOAPException {
146         return SAAJMetaFactory.getInstance().newMessageFactory(protocol);
147     }
148 
149     /**
150      * Creates a new <code>SOAPMessage</code> object with the default
151      * <code>SOAPPart</code>, <code>SOAPEnvelope</code>, <code>SOAPBody</code>,
152      * and <code>SOAPHeader</code> objects. Profile-specific message factories
153      * can choose to prepopulate the <code>SOAPMessage</code> object with
154      * profile-specific headers.
155      * <P>
156      * Content can be added to this message's <code>SOAPPart</code> object, and
157      * the message can be sent "as is" when a message containing only a SOAP part
158      * is sufficient. Otherwise, the <code>SOAPMessage</code> object needs
159      * to create one or more <code>AttachmentPart</code> objects and
160      * add them to itself. Any content that is not in XML format must be
161      * in an <code>AttachmentPart</code> object.
162      *
163      * @return a new <code>SOAPMessage</code> object
164      * @exception SOAPException if a SOAP error occurs
165      * @exception UnsupportedOperationException if the protocol of this
166      *      <code>MessageFactory</code> instance is <code>DYNAMIC_SOAP_PROTOCOL</code>
167      */
168     public abstract SOAPMessage createMessage()
169         throws SOAPException;
170 
171     /**
172      * Internalizes the contents of the given <code>InputStream</code> object into a
173      * new <code>SOAPMessage</code> object and returns the <code>SOAPMessage</code>
174      * object.
175      *
176      * @param in the <code>InputStream</code> object that contains the data
177      *           for a message
178      * @param headers the transport-specific headers passed to the
179      *        message in a transport-independent fashion for creation of the
180      *        message
181      * @return a new <code>SOAPMessage</code> object containing the data from
182      *         the given <code>InputStream</code> object
183      *
184      * @exception IOException if there is a problem in reading data from
185      *            the input stream
186      *
187      * @exception SOAPException may be thrown if the message is invalid
188      *
189      * @exception IllegalArgumentException if the <code>MessageFactory</code>
190      *      requires one or more MIME headers to be present in the
191      *      <code>headers</code> parameter and they are missing.
192      *      <code>MessageFactory</code> implementations for
193      *      <code>SOAP_1_1_PROTOCOL</code> or
194      *      <code>SOAP_1_2_PROTOCOL</code> must not throw
195      *      <code>IllegalArgumentException</code> for this reason.
196      */
197     public abstract SOAPMessage createMessage(MimeHeaders headers,
198                                               InputStream in)
199         throws IOException, SOAPException;
200 }