1 /*
   2  * Copyright (c) 2004, 2017, 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} is a factory for creating various objects
  34  * that exist in the SOAP XML tree.
  35 
  36  * {@code SOAPFactory} 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} also has methods to create
  43  * {@code javax.xml.soap.Detail} objects as well as
  44  * {@code java.xml.soap.Name} objects.
  45  *
  46  * @since 1.6
  47  */
  48 public abstract class SOAPFactory {
  49 
  50     /**
  51      * Class name of default {@code SOAPFactory} implementation.
  52      */
  53     private static final String DEFAULT_SOAP_FACTORY
  54             = "com.sun.xml.internal.messaging.saaj.soap.ver1_1.SOAPFactory1_1Impl";
  55 
  56     /**
  57      * Creates a {@code SOAPElement} object from an existing DOM
  58      * {@code Element}. If the DOM {@code Element} that is passed in
  59      * as an argument is already a {@code SOAPElement} then this method
  60      * must return it unmodified without any further work. Otherwise, a new
  61      * {@code SOAPElement} is created and a deep copy is made of the
  62      * {@code domElement} argument. The concrete type of the return value
  63      * will depend on the name of the {@code domElement} argument. If any
  64      * part of the tree rooted in {@code domElement} violates SOAP rules, a
  65      * {@code SOAPException} will be thrown.
  66      *
  67      * @param domElement - the {@code Element} to be copied.
  68      *
  69      * @return a new {@code SOAPElement} that is a copy of {@code domElement}.
  70      *
  71      * @exception SOAPException if there is an error in creating the
  72      *            {@code SOAPElement} object
  73      *
  74      * @since 1.6, SAAJ 1.3
  75      */
  76     public SOAPElement createElement(Element domElement) throws SOAPException {
  77         throw new UnsupportedOperationException("createElement(org.w3c.dom.Element) must be overridden by all subclasses of SOAPFactory.");
  78     }
  79 
  80     /**
  81      * Creates a {@code SOAPElement} object initialized with the
  82      * given {@code Name} object. The concrete type of the return value
  83      * will depend on the name given to the new {@code SOAPElement}. For
  84      * instance, a new {@code SOAPElement} with the name
  85      * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a
  86      * {@code SOAPEnvelope} that supports SOAP 1.2 behavior to be created.
  87      *
  88      * @param name a {@code Name} object with the XML name for
  89      *             the new element
  90      *
  91      * @return the new {@code SOAPElement} object that was
  92      *         created
  93      *
  94      * @exception SOAPException if there is an error in creating the
  95      *            {@code SOAPElement} object
  96      * @see SOAPFactory#createElement(javax.xml.namespace.QName)
  97      */
  98     public abstract SOAPElement createElement(Name name) throws SOAPException;
  99 
 100     /**
 101      * Creates a {@code SOAPElement} object initialized with the
 102      * given {@code QName} object. The concrete type of the return value
 103      * will depend on the name given to the new {@code SOAPElement}. For
 104      * instance, a new {@code SOAPElement} with the name
 105      * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a
 106      * {@code SOAPEnvelope} that supports SOAP 1.2 behavior to be created.
 107      *
 108      * @param qname a {@code QName} object with the XML name for
 109      *             the new element
 110      *
 111      * @return the new {@code SOAPElement} object that was
 112      *         created
 113      *
 114      * @exception SOAPException if there is an error in creating the
 115      *            {@code SOAPElement} object
 116      * @see SOAPFactory#createElement(Name)
 117      * @since 1.6, SAAJ 1.3
 118      */
 119     public  SOAPElement createElement(QName qname) throws SOAPException {
 120         throw new UnsupportedOperationException("createElement(QName) must be overridden by all subclasses of SOAPFactory.");
 121     }
 122 
 123     /**
 124      * Creates a {@code SOAPElement} object initialized with the
 125      * given local name.
 126      *
 127      * @param localName a {@code String} giving the local name for
 128      *             the new element
 129      *
 130      * @return the new {@code SOAPElement} object that was
 131      *         created
 132      *
 133      * @exception SOAPException if there is an error in creating the
 134      *            {@code SOAPElement} object
 135      */
 136     public abstract SOAPElement createElement(String localName)
 137         throws SOAPException;
 138 
 139 
 140     /**
 141      * Creates a new {@code SOAPElement} object with the given
 142      * local name, prefix and uri. The concrete type of the return value
 143      * will depend on the name given to the new {@code SOAPElement}. For
 144      * instance, a new {@code SOAPElement} with the name
 145      * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a
 146      * {@code SOAPEnvelope} that supports SOAP 1.2 behavior to be created.
 147      *
 148      * @param localName a {@code String} giving the local name
 149      *                  for the new element
 150      * @param prefix the prefix for this {@code SOAPElement}
 151      * @param uri a {@code String} giving the URI of the
 152      *            namespace to which the new element belongs
 153      * @return the new {@code SOAPElement} object that was
 154      *         created
 155      *
 156      * @exception SOAPException if there is an error in creating the
 157      *            {@code SOAPElement} object
 158      */
 159     public abstract SOAPElement createElement(
 160         String localName,
 161         String prefix,
 162         String uri)
 163         throws SOAPException;
 164 
 165     /**
 166      * Creates a new {@code Detail} object which serves as a container
 167      * for {@code DetailEntry} objects.
 168      * <P>
 169      * This factory method creates {@code Detail} objects for use in
 170      * situations where it is not practical to use the {@code SOAPFault}
 171      * abstraction.
 172      *
 173      * @return a {@code Detail} object
 174      * @throws SOAPException if there is a SOAP error
 175      * @throws UnsupportedOperationException if the protocol specified
 176      *         for the SOAPFactory was {@code DYNAMIC_SOAP_PROTOCOL}
 177      */
 178     public abstract Detail createDetail() throws SOAPException;
 179 
 180     /**
 181      *Creates a new {@code SOAPFault} object initialized with the given {@code reasonText}
 182      *  and {@code faultCode}
 183      *@param reasonText the ReasonText/FaultString for the fault
 184      *@param faultCode the FaultCode for the fault
 185      *@return a {@code SOAPFault} object
 186      *@throws SOAPException if there is a SOAP error
 187      *@since 1.6, SAAJ 1.3
 188      */
 189     public abstract SOAPFault createFault(String reasonText, QName faultCode) throws SOAPException;
 190 
 191     /**
 192      *Creates a new default {@code SOAPFault} object
 193      *@return a {@code SOAPFault} object
 194      *@throws SOAPException if there is a SOAP error
 195      *@since 1.6, SAAJ 1.3
 196      */
 197     public abstract SOAPFault createFault() throws SOAPException;
 198 
 199     /**
 200      * Creates a new {@code Name} object initialized with the
 201      * given local name, namespace prefix, and namespace URI.
 202      * <P>
 203      * This factory method creates {@code Name} objects for use in
 204      * situations where it is not practical to use the {@code SOAPEnvelope}
 205      * abstraction.
 206      *
 207      * @param localName a {@code String} giving the local name
 208      * @param prefix a {@code String} giving the prefix of the namespace
 209      * @param uri a {@code String} giving the URI of the namespace
 210      * @return a {@code Name} object initialized with the given
 211      *         local name, namespace prefix, and namespace URI
 212      * @throws SOAPException if there is a SOAP error
 213      */
 214     public abstract Name createName(
 215         String localName,
 216         String prefix,
 217         String uri)
 218         throws SOAPException;
 219 
 220     /**
 221      * Creates a new {@code Name} object initialized with the
 222      * given local name.
 223      * <P>
 224      * This factory method creates {@code Name} objects for use in
 225      * situations where it is not practical to use the {@code SOAPEnvelope}
 226      * abstraction.
 227      *
 228      * @param localName a {@code String} giving the local name
 229      * @return a {@code Name} object initialized with the given
 230      *         local name
 231      * @throws SOAPException if there is a SOAP error
 232      */
 233     public abstract Name createName(String localName) throws SOAPException;
 234 
 235     /**
 236      * Creates a new {@code SOAPFactory} object that is an instance of
 237      * the default implementation (SOAP 1.1).
 238      *
 239      * This method uses the lookup procedure specified in {@link javax.xml.soap} to locate and load the
 240      * {@link javax.xml.soap.SOAPFactory} class.
 241      *
 242      * @return a new instance of a {@code SOAPFactory}
 243      *
 244      * @exception SOAPException if there was an error creating the
 245      *            default {@code SOAPFactory}
 246      * @see SAAJMetaFactory
 247      */
 248     public static SOAPFactory newInstance()
 249         throws SOAPException
 250     {
 251         try {
 252             SOAPFactory factory = FactoryFinder.find(
 253                     SOAPFactory.class,
 254                     DEFAULT_SOAP_FACTORY,
 255                     false);
 256             if (factory != null) return factory;
 257 
 258             // leave it on SAAJMetaFactory
 259             return newInstance(SOAPConstants.SOAP_1_1_PROTOCOL);
 260         } catch (Exception ex) {
 261             throw new SOAPException(
 262                 "Unable to create SOAP Factory: " + ex.getMessage());
 263         }
 264 
 265     }
 266 
 267     /**
 268      * Creates a new {@code SOAPFactory} object that is an instance of
 269      * the specified implementation, this method uses the SAAJMetaFactory to
 270      * locate the implementation class and create the SOAPFactory instance.
 271      *
 272      * @return a new instance of a {@code SOAPFactory}
 273      *
 274      * @param protocol  a string constant representing the protocol of the
 275      *                   specified SOAP factory implementation. May be
 276      *                   either {@code DYNAMIC_SOAP_PROTOCOL},
 277      *                   {@code DEFAULT_SOAP_PROTOCOL} (which is the same
 278      *                   as) {@code SOAP_1_1_PROTOCOL}, or
 279      *                   {@code SOAP_1_2_PROTOCOL}.
 280      *
 281      * @exception SOAPException if there was an error creating the
 282      *            specified {@code SOAPFactory}
 283      * @see SAAJMetaFactory
 284      * @since 1.6, SAAJ 1.3
 285      */
 286     public static SOAPFactory newInstance(String protocol)
 287         throws SOAPException {
 288             return SAAJMetaFactory.getInstance().newSOAPFactory(protocol);
 289     }
 290 }