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 * The access point for the implementation classes of the factories defined in the

    30 * SAAJ API. All of the <code>newInstance</code> methods defined on factories in

    31 * SAAJ 1.3 defer to instances of this class to do the actual object creation.

    32 * The implementations of <code>newInstance()</code> methods (in SOAPFactory and MessageFactory)

    33 * that existed in SAAJ 1.2 have been updated to also delegate to the SAAJMetaFactory when the SAAJ 1.2

    34 * defined lookup fails to locate the Factory implementation class name.

    35 *

    36 * <p>

    37 * SAAJMetaFactory is a service provider interface. There are no public methods on this

    38 * class.

    39 *

    40 * @author SAAJ RI Development Team

    41 * @since 1.6, SAAJ 1.3

    42 */

    43 

    44 public abstract class SAAJMetaFactory {

    45     static private final String META_FACTORY_CLASS_PROPERTY =

    46         "javax.xml.soap.MetaFactory";

    47     static final String DEFAULT_META_FACTORY_CLASS =

    48         "com.sun.xml.internal.messaging.saaj.soap.SAAJMetaFactoryImpl";

    49 

    50     /**

    51      * Creates a new instance of a concrete <code>SAAJMetaFactory</code> object.

    52      * The SAAJMetaFactory is an SPI, it pulls the creation of the other factories together into a

    53      * single place. Changing out the SAAJMetaFactory has the effect of changing out the entire SAAJ

    54      * implementation. Service providers provide the name of their <code>SAAJMetaFactory</code>

    55      * implementation.

    56      *

    57      * This method uses the following ordered lookup procedure to determine the SAAJMetaFactory implementation class to load:

    58      * <UL>

    59      *  <LI> Use the javax.xml.soap.MetaFactory system property.

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

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

    62      * system property defined above.

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

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

    65      *  <LI> Default to com.sun.xml.internal.messaging.saaj.soap.SAAJMetaFactoryImpl.

    66      * </UL>

    67      *

    68      * @return a concrete <code>SAAJMetaFactory</code> object

    69      * @exception SOAPException if there is an error in creating the <code>SAAJMetaFactory</code>

    70      */

    71     static SAAJMetaFactory getInstance() throws SOAPException {

    72             try {

    73                 SAAJMetaFactory instance =

    74                     (SAAJMetaFactory) FactoryFinder.find(

    75                         META_FACTORY_CLASS_PROPERTY,

    76                         DEFAULT_META_FACTORY_CLASS);

    77                 return instance;

    78             } catch (Exception e) {

    79                 throw new SOAPException(

    80                     "Unable to create SAAJ meta-factory" + e.getMessage());

    81             }

    82     }

    83 

    84     protected SAAJMetaFactory() { }

    85 

    86      /**

    87       * Creates a <code>MessageFactory</code> object for

    88       * the given <code>String</code> protocol.

    89       *

    90       * @param protocol a <code>String</code> indicating the protocol

    91       * @exception SOAPException if there is an error in creating the

    92       *            MessageFactory

    93       * @see SOAPConstants#SOAP_1_1_PROTOCOL

    94       * @see SOAPConstants#SOAP_1_2_PROTOCOL

    95       * @see SOAPConstants#DYNAMIC_SOAP_PROTOCOL

    96       */

    97     protected abstract MessageFactory newMessageFactory(String protocol)

    98         throws SOAPException;

    99 

   100      /**

   101       * Creates a <code>SOAPFactory</code> object for

   102       * the given <code>String</code> protocol.

   103       *

   104       * @param protocol a <code>String</code> indicating the protocol

   105       * @exception SOAPException if there is an error in creating the

   106       *            SOAPFactory

   107       * @see SOAPConstants#SOAP_1_1_PROTOCOL

   108       * @see SOAPConstants#SOAP_1_2_PROTOCOL

   109       * @see SOAPConstants#DYNAMIC_SOAP_PROTOCOL

   110       */

   111     protected abstract SOAPFactory newSOAPFactory(String protocol)

   112         throws SOAPException;

   113 }