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 import javax.xml.namespace.QName;

    29 

    30 import org.w3c.dom.Element;

    31 

    32 /**

    33  * <code>SOAPFactory</code> is a factory for creating various objects

    34  * that exist in the SOAP XML tree.

    35 

    36  * <code>SOAPFactory</code> can be

    37  * used to create XML fragments that will eventually end up in the

    38  * SOAP part. These fragments can be inserted as children of the

    39  * {@link SOAPHeaderElement} or {@link SOAPBodyElement} or

    40  * {@link SOAPEnvelope} or other {@link SOAPElement} objects.

    41  *

    42  * <code>SOAPFactory</code> also has methods to create

    43  * <code>javax.xml.soap.Detail</code> objects as well as

    44  * <code>java.xml.soap.Name</code> objects.

    45  *

    46  * @since 1.6

    47  */

    48 public abstract class SOAPFactory {

    49 

    50     /**

    51      * A constant representing the property used to lookup the name of

    52      * a <code>SOAPFactory</code> implementation class.

    53      */

    54     static private final String SOAP_FACTORY_PROPERTY =

    55         "javax.xml.soap.SOAPFactory";

    56 

    57     /**

    58      * Class name of default <code>SOAPFactory</code> implementation.

    59      */

    60     static final String DEFAULT_SOAP_FACTORY

    61         = "com.sun.xml.internal.messaging.saaj.soap.ver1_1.SOAPFactory1_1Impl";

    62 

    63     /**

    64      * Creates a <code>SOAPElement</code> object from an existing DOM

    65      * <code>Element</code>. If the DOM <code>Element</code> that is passed in

    66      * as an argument is already a <code>SOAPElement</code> then this method

    67      * must return it unmodified without any further work. Otherwise, a new

    68      * <code>SOAPElement</code> is created and a deep copy is made of the

    69      * <code>domElement</code> argument. The concrete type of the return value

    70      * will depend on the name of the <code>domElement</code> argument. If any

    71      * part of the tree rooted in <code>domElement</code> violates SOAP rules, a

    72      * <code>SOAPException</code> will be thrown.

    73      *

    74      * @param domElement - the <code>Element</code> to be copied.

    75      *

    76      * @return a new <code>SOAPElement</code> that is a copy of <code>domElement</code>.

    77      *

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

    79      *            <code>SOAPElement</code> object

    80      *

    81      * @since 1.6, SAAJ 1.3

    82      */

    83     public SOAPElement createElement(Element domElement) throws SOAPException {

    84         throw new UnsupportedOperationException("createElement(org.w3c.dom.Element) must be overridden by all subclasses of SOAPFactory.");

    85     }

    86 

    87     /**

    88      * Creates a <code>SOAPElement</code> object initialized with the

    89      * given <code>Name</code> object. The concrete type of the return value

    90      * will depend on the name given to the new <code>SOAPElement</code>. For

    91      * instance, a new <code>SOAPElement</code> with the name

    92      * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a

    93      * <code>SOAPEnvelope</code> that supports SOAP 1.2 behavior to be created.

    94      *

    95      * @param name a <code>Name</code> object with the XML name for

    96      *             the new element

    97      *

    98      * @return the new <code>SOAPElement</code> object that was

    99      *         created

   100      *

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

   102      *            <code>SOAPElement</code> object

   103      * @see SOAPFactory#createElement(javax.xml.namespace.QName)

   104      */

   105     public abstract SOAPElement createElement(Name name) throws SOAPException;

   106 

   107     /**

   108      * Creates a <code>SOAPElement</code> object initialized with the

   109      * given <code>QName</code> object. The concrete type of the return value

   110      * will depend on the name given to the new <code>SOAPElement</code>. For

   111      * instance, a new <code>SOAPElement</code> with the name

   112      * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a

   113      * <code>SOAPEnvelope</code> that supports SOAP 1.2 behavior to be created.

   114      *

   115      * @param qname a <code>QName</code> object with the XML name for

   116      *             the new element

   117      *

   118      * @return the new <code>SOAPElement</code> object that was

   119      *         created

   120      *

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

   122      *            <code>SOAPElement</code> object

   123      * @see SOAPFactory#createElement(Name)

   124      * @since 1.6, SAAJ 1.3

   125      */

   126     public  SOAPElement createElement(QName qname) throws SOAPException {

   127         throw new UnsupportedOperationException("createElement(QName) must be overridden by all subclasses of SOAPFactory.");

   128     }

   129 

   130     /**

   131      * Creates a <code>SOAPElement</code> object initialized with the

   132      * given local name.

   133      *

   134      * @param localName a <code>String</code> giving the local name for

   135      *             the new element

   136      *

   137      * @return the new <code>SOAPElement</code> object that was

   138      *         created

   139      *

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

   141      *            <code>SOAPElement</code> object

   142      */

   143     public abstract SOAPElement createElement(String localName)

   144         throws SOAPException;

   145 

   146 

   147     /**

   148      * Creates a new <code>SOAPElement</code> object with the given

   149      * local name, prefix and uri. The concrete type of the return value

   150      * will depend on the name given to the new <code>SOAPElement</code>. For

   151      * instance, a new <code>SOAPElement</code> with the name

   152      * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a

   153      * <code>SOAPEnvelope</code> that supports SOAP 1.2 behavior to be created.

   154      *

   155      * @param localName a <code>String</code> giving the local name

   156      *                  for the new element

   157      * @param prefix the prefix for this <code>SOAPElement</code>

   158      * @param uri a <code>String</code> giving the URI of the

   159      *            namespace to which the new element belongs

   160      *

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

   162      *            <code>SOAPElement</code> object

   163      */

   164     public abstract SOAPElement createElement(

   165         String localName,

   166         String prefix,

   167         String uri)

   168         throws SOAPException;

   169 

   170     /**

   171      * Creates a new <code>Detail</code> object which serves as a container

   172      * for <code>DetailEntry</code> objects.

   173      * <P>

   174      * This factory method creates <code>Detail</code> objects for use in

   175      * situations where it is not practical to use the <code>SOAPFault</code>

   176      * abstraction.

   177      *

   178      * @return a <code>Detail</code> object

   179      * @throws SOAPException if there is a SOAP error

   180      * @throws UnsupportedOperationException if the protocol specified

   181      *         for the SOAPFactory was <code>DYNAMIC_SOAP_PROTOCOL</code>

   182      */

   183     public abstract Detail createDetail() throws SOAPException;

   184 

   185     /**

   186      *Creates a new <code>SOAPFault</code> object initialized with the given <code>reasonText</code>

   187      *  and <code>faultCode</code>

   188      *@param reasonText the ReasonText/FaultString for the fault

   189      *@param faultCode the FaultCode for the fault

   190      *@return a <code>SOAPFault</code> object

   191      *@throws SOAPException if there is a SOAP error

   192      *@since 1.6, SAAJ 1.3

   193      */

   194     public abstract SOAPFault createFault(String reasonText, QName faultCode) throws SOAPException;

   195 

   196     /**

   197      *Creates a new default <code>SOAPFault</code> object

   198      *@return a <code>SOAPFault</code> object

   199      *@throws SOAPException if there is a SOAP error

   200      *@since 1.6, SAAJ 1.3

   201      */

   202     public abstract SOAPFault createFault() throws SOAPException;

   203 

   204     /**

   205      * Creates a new <code>Name</code> object initialized with the

   206      * given local name, namespace prefix, and namespace URI.

   207      * <P>

   208      * This factory method creates <code>Name</code> objects for use in

   209      * situations where it is not practical to use the <code>SOAPEnvelope</code>

   210      * abstraction.

   211      *

   212      * @param localName a <code>String</code> giving the local name

   213      * @param prefix a <code>String</code> giving the prefix of the namespace

   214      * @param uri a <code>String</code> giving the URI of the namespace

   215      * @return a <code>Name</code> object initialized with the given

   216      *         local name, namespace prefix, and namespace URI

   217      * @throws SOAPException if there is a SOAP error

   218      */

   219     public abstract Name createName(

   220         String localName,

   221         String prefix,

   222         String uri)

   223         throws SOAPException;

   224 

   225     /**

   226      * Creates a new <code>Name</code> object initialized with the

   227      * given local name.

   228      * <P>

   229      * This factory method creates <code>Name</code> objects for use in

   230      * situations where it is not practical to use the <code>SOAPEnvelope</code>

   231      * abstraction.

   232      *

   233      * @param localName a <code>String</code> giving the local name

   234      * @return a <code>Name</code> object initialized with the given

   235      *         local name

   236      * @throws SOAPException if there is a SOAP error

   237      */

   238     public abstract Name createName(String localName) throws SOAPException;

   239 

   240     /**

   241      * Creates a new <code>SOAPFactory</code> object that is an instance of

   242      * the default implementation (SOAP 1.1),

   243      *

   244      * This method uses the following ordered lookup procedure to determine the SOAPFactory implementation class to load:

   245      * <UL>

   246      *  <LI> Use the javax.xml.soap.SOAPFactory system property.

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

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

   249      * system property defined above.

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

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

   252      *  <LI> Use the SAAJMetaFactory instance to locate the SOAPFactory implementation class.

   253      * </UL>

   254      *

   255      * @return a new instance of a <code>SOAPFactory</code>

   256      *

   257      * @exception SOAPException if there was an error creating the

   258      *            default <code>SOAPFactory</code>

   259      * @see SAAJMetaFactory

   260      */

   261     public static SOAPFactory newInstance()

   262         throws SOAPException

   263     {

   264         try {

   265             SOAPFactory factory = (SOAPFactory) FactoryFinder.find(

   266                     SOAP_FACTORY_PROPERTY, DEFAULT_SOAP_FACTORY, false);

   267             if (factory != null)

   268                 return factory;

   269             return newInstance(SOAPConstants.SOAP_1_1_PROTOCOL);

   270         } catch (Exception ex) {

   271             throw new SOAPException(

   272                 "Unable to create SOAP Factory: " + ex.getMessage());

   273         }

   274 

   275     }

   276 

   277     /**

   278      * Creates a new <code>SOAPFactory</code> object that is an instance of

   279      * the specified implementation, this method uses the SAAJMetaFactory to

   280      * locate the implementation class and create the SOAPFactory instance.

   281      *

   282      * @return a new instance of a <code>SOAPFactory</code>

   283      *

   284      * @param protocol  a string constant representing the protocol of the

   285      *                   specified SOAP factory implementation. May be

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

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

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

   289      *                   <code>SOAP_1_2_PROTOCOL</code>.

   290      *

   291      * @exception SOAPException if there was an error creating the

   292      *            specified <code>SOAPFactory</code>

   293      * @see SAAJMetaFactory

   294      * @since 1.6, SAAJ 1.3

   295      */

   296     public static SOAPFactory newInstance(String protocol)

   297         throws SOAPException {

   298             return SAAJMetaFactory.getInstance().newSOAPFactory(protocol);

   299     }

   300 }