1 /*
   2  * Copyright (c) 2004, 2015, 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      *
 154      * @exception SOAPException if there is an error in creating the
 155      *            {@code SOAPElement} object
 156      */
 157     public abstract SOAPElement createElement(
 158         String localName,
 159         String prefix,
 160         String uri)
 161         throws SOAPException;
 162 
 163     /**
 164      * Creates a new {@code Detail} object which serves as a container
 165      * for {@code DetailEntry} objects.
 166      * <P>
 167      * This factory method creates {@code Detail} objects for use in
 168      * situations where it is not practical to use the {@code SOAPFault}
 169      * abstraction.
 170      *
 171      * @return a {@code Detail} object
 172      * @throws SOAPException if there is a SOAP error
 173      * @throws UnsupportedOperationException if the protocol specified
 174      *         for the SOAPFactory was {@code DYNAMIC_SOAP_PROTOCOL}
 175      */
 176     public abstract Detail createDetail() throws SOAPException;
 177 
 178     /**
 179      *Creates a new {@code SOAPFault} object initialized with the given {@code reasonText}
 180      *  and {@code faultCode}
 181      *@param reasonText the ReasonText/FaultString for the fault
 182      *@param faultCode the FaultCode for the fault
 183      *@return a {@code SOAPFault} object
 184      *@throws SOAPException if there is a SOAP error
 185      *@since 1.6, SAAJ 1.3
 186      */
 187     public abstract SOAPFault createFault(String reasonText, QName faultCode) throws SOAPException;
 188 
 189     /**
 190      *Creates a new default {@code SOAPFault} object
 191      *@return a {@code SOAPFault} object
 192      *@throws SOAPException if there is a SOAP error
 193      *@since 1.6, SAAJ 1.3
 194      */
 195     public abstract SOAPFault createFault() throws SOAPException;
 196 
 197     /**
 198      * Creates a new {@code Name} object initialized with the
 199      * given local name, namespace prefix, and namespace URI.
 200      * <P>
 201      * This factory method creates {@code Name} objects for use in
 202      * situations where it is not practical to use the {@code SOAPEnvelope}
 203      * abstraction.
 204      *
 205      * @param localName a {@code String} giving the local name
 206      * @param prefix a {@code String} giving the prefix of the namespace
 207      * @param uri a {@code String} giving the URI of the namespace
 208      * @return a {@code Name} object initialized with the given
 209      *         local name, namespace prefix, and namespace URI
 210      * @throws SOAPException if there is a SOAP error
 211      */
 212     public abstract Name createName(
 213         String localName,
 214         String prefix,
 215         String uri)
 216         throws SOAPException;
 217 
 218     /**
 219      * Creates a new {@code Name} object initialized with the
 220      * given local name.
 221      * <P>
 222      * This factory method creates {@code Name} objects for use in
 223      * situations where it is not practical to use the {@code SOAPEnvelope}
 224      * abstraction.
 225      *
 226      * @param localName a {@code String} giving the local name
 227      * @return a {@code Name} object initialized with the given
 228      *         local name
 229      * @throws SOAPException if there is a SOAP error
 230      */
 231     public abstract Name createName(String localName) throws SOAPException;
 232 
 233     /**
 234      * Creates a new {@code SOAPFactory} object that is an instance of
 235      * the default implementation (SOAP 1.1).
 236      *
 237      * This method uses the lookup procedure specified in {@link javax.xml.soap} to locate and load the
 238      * {@link javax.xml.soap.SOAPFactory} class.
 239      *
 240      * @return a new instance of a {@code SOAPFactory}
 241      *
 242      * @exception SOAPException if there was an error creating the
 243      *            default {@code SOAPFactory}
 244      * @see SAAJMetaFactory
 245      */
 246     public static SOAPFactory newInstance()
 247         throws SOAPException
 248     {
 249         try {
 250             SOAPFactory factory = FactoryFinder.find(
 251                     SOAPFactory.class,
 252                     DEFAULT_SOAP_FACTORY,
 253                     false);
 254             if (factory != null) return factory;
 255 
 256             // leave it on SAAJMetaFactory
 257             return newInstance(SOAPConstants.SOAP_1_1_PROTOCOL);
 258         } catch (Exception ex) {
 259             throw new SOAPException(
 260                 "Unable to create SOAP Factory: " + ex.getMessage());
 261         }
 262 
 263     }
 264 
 265     /**
 266      * Creates a new {@code SOAPFactory} object that is an instance of
 267      * the specified implementation, this method uses the SAAJMetaFactory to
 268      * locate the implementation class and create the SOAPFactory instance.
 269      *
 270      * @return a new instance of a {@code SOAPFactory}
 271      *
 272      * @param protocol  a string constant representing the protocol of the
 273      *                   specified SOAP factory implementation. May be
 274      *                   either {@code DYNAMIC_SOAP_PROTOCOL},
 275      *                   {@code DEFAULT_SOAP_PROTOCOL} (which is the same
 276      *                   as) {@code SOAP_1_1_PROTOCOL}, or
 277      *                   {@code SOAP_1_2_PROTOCOL}.
 278      *
 279      * @exception SOAPException if there was an error creating the
 280      *            specified {@code SOAPFactory}
 281      * @see SAAJMetaFactory
 282      * @since 1.6, SAAJ 1.3
 283      */
 284     public static SOAPFactory newInstance(String protocol)
 285         throws SOAPException {
 286             return SAAJMetaFactory.getInstance().newSOAPFactory(protocol);
 287     }
 288 }
--- EOF ---