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 }
--- EOF ---