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  * @since 1.6

    68  */

    69 public abstract class MessageFactory {

    70 

    71     static final String DEFAULT_MESSAGE_FACTORY

    72         = "com.sun.xml.internal.messaging.saaj.soap.ver1_1.SOAPMessageFactory1_1Impl";

    73 

    74     static private final String MESSAGE_FACTORY_PROPERTY

    75         = "javax.xml.soap.MessageFactory";

    76 

    77     /**

    78      * Creates a new <code>MessageFactory</code> object that is an instance

    79      * of the default implementation (SOAP 1.1),

    80      *

    81      * This method uses the following ordered lookup procedure to determine the MessageFactory implementation class to load:

    82      * <UL>

    83      *  <LI> Use the javax.xml.soap.MessageFactory system property.

    84      *  <LI> Use the properties file "lib/jaxm.properties" in the JRE directory. This configuration file is in standard

    85      * java.util.Properties format and contains the fully qualified name of the implementation class with the key being the

    86      * system property defined above.

    87      *  <LI> Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API

    88      * will look for a classname in the file META-INF/services/javax.xml.soap.MessageFactory in jars available to the runtime.

    89      *  <LI> Use the SAAJMetaFactory instance to locate the MessageFactory implementation class.

    90      * </UL>

    91 

    92      *

    93      * @return a new instance of a <code>MessageFactory</code>

    94      *

    95      * @exception SOAPException if there was an error in creating the

    96      *            default implementation of the

    97      *            <code>MessageFactory</code>.

    98      * @see SAAJMetaFactory

    99      */

   100 

   101     public static MessageFactory newInstance() throws SOAPException {

   102 

   103 

   104         try {

   105             MessageFactory factory = (MessageFactory) FactoryFinder.find(

   106                     MESSAGE_FACTORY_PROPERTY,

   107                     DEFAULT_MESSAGE_FACTORY,

   108                     false);

   109 

   110             if (factory != null) {

   111                 return factory;

   112             }

   113             return newInstance(SOAPConstants.SOAP_1_1_PROTOCOL);

   114 

   115         } catch (Exception ex) {

   116             throw new SOAPException(

   117                     "Unable to create message factory for SOAP: "

   118                                     +ex.getMessage());

   119         }

   120 

   121     }

   122 

   123     /**

   124      * Creates a new <code>MessageFactory</code> object that is an instance

   125      * of the specified implementation.  May be a dynamic message factory,

   126      * a SOAP 1.1 message factory, or a SOAP 1.2 message factory. A dynamic

   127      * message factory creates messages based on the MIME headers specified

   128      * as arguments to the <code>createMessage</code> method.

   129      *

   130      * This method uses the SAAJMetaFactory to locate the implementation class

   131      * and create the MessageFactory instance.

   132      *

   133      * @return a new instance of a <code>MessageFactory</code>

   134      *

   135      * @param protocol  a string constant representing the class of the

   136      *                   specified message factory implementation. May be

   137      *                   either <code>DYNAMIC_SOAP_PROTOCOL</code>,

   138      *                   <code>DEFAULT_SOAP_PROTOCOL</code> (which is the same

   139      *                   as) <code>SOAP_1_1_PROTOCOL</code>, or

   140      *                   <code>SOAP_1_2_PROTOCOL</code>.

   141      *

   142      * @exception SOAPException if there was an error in creating the

   143      *            specified implementation of  <code>MessageFactory</code>.

   144      * @see SAAJMetaFactory

   145      * @since 1.6, SAAJ 1.3

   146      */

   147     public static MessageFactory newInstance(String protocol) throws SOAPException {

   148         return SAAJMetaFactory.getInstance().newMessageFactory(protocol);

   149     }

   150 

   151     /**

   152      * Creates a new <code>SOAPMessage</code> object with the default

   153      * <code>SOAPPart</code>, <code>SOAPEnvelope</code>, <code>SOAPBody</code>,

   154      * and <code>SOAPHeader</code> objects. Profile-specific message factories

   155      * can choose to prepopulate the <code>SOAPMessage</code> object with

   156      * profile-specific headers.

   157      * <P>

   158      * Content can be added to this message's <code>SOAPPart</code> object, and

   159      * the message can be sent "as is" when a message containing only a SOAP part

   160      * is sufficient. Otherwise, the <code>SOAPMessage</code> object needs

   161      * to create one or more <code>AttachmentPart</code> objects and

   162      * add them to itself. Any content that is not in XML format must be

   163      * in an <code>AttachmentPart</code> object.

   164      *

   165      * @return a new <code>SOAPMessage</code> object

   166      * @exception SOAPException if a SOAP error occurs

   167      * @exception UnsupportedOperationException if the protocol of this

   168      *      <code>MessageFactory</code> instance is <code>DYNAMIC_SOAP_PROTOCOL</code>

   169      */

   170     public abstract SOAPMessage createMessage()

   171         throws SOAPException;

   172 

   173     /**

   174      * Internalizes the contents of the given <code>InputStream</code> object into a

   175      * new <code>SOAPMessage</code> object and returns the <code>SOAPMessage</code>

   176      * object.

   177      *

   178      * @param in the <code>InputStream</code> object that contains the data

   179      *           for a message

   180      * @param headers the transport-specific headers passed to the

   181      *        message in a transport-independent fashion for creation of the

   182      *        message

   183      * @return a new <code>SOAPMessage</code> object containing the data from

   184      *         the given <code>InputStream</code> object

   185      *

   186      * @exception IOException if there is a problem in reading data from

   187      *            the input stream

   188      *

   189      * @exception SOAPException may be thrown if the message is invalid

   190      *

   191      * @exception IllegalArgumentException if the <code>MessageFactory</code>

   192      *      requires one or more MIME headers to be present in the

   193      *      <code>headers</code> parameter and they are missing.

   194      *      <code>MessageFactory</code> implementations for

   195      *      <code>SOAP_1_1_PROTOCOL</code> or

   196      *      <code>SOAP_1_2_PROTOCOL</code> must not throw

   197      *      <code>IllegalArgumentException</code> for this reason.

   198      */

   199     public abstract SOAPMessage createMessage(MimeHeaders headers,

   200                                               InputStream in)

   201         throws IOException, SOAPException;

   202 }