/* * Copyright (c) 2004, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.xml.soap; import javax.xml.namespace.QName; import org.w3c.dom.Element; /** * SOAPFactory is a factory for creating various objects * that exist in the SOAP XML tree. * SOAPFactory can be * used to create XML fragments that will eventually end up in the * SOAP part. These fragments can be inserted as children of the * {@link SOAPHeaderElement} or {@link SOAPBodyElement} or * {@link SOAPEnvelope} or other {@link SOAPElement} objects. * * SOAPFactory also has methods to create * javax.xml.soap.Detail objects as well as * java.xml.soap.Name objects. * * @since 1.6 */ public abstract class SOAPFactory { /** * A constant representing the property used to lookup the name of * a SOAPFactory implementation class. */ static private final String SOAP_FACTORY_PROPERTY = "javax.xml.soap.SOAPFactory"; /** * Class name of default SOAPFactory implementation. */ static final String DEFAULT_SOAP_FACTORY = "com.sun.xml.internal.messaging.saaj.soap.ver1_1.SOAPFactory1_1Impl"; /** * Creates a SOAPElement object from an existing DOM * Element. If the DOM Element that is passed in * as an argument is already a SOAPElement then this method * must return it unmodified without any further work. Otherwise, a new * SOAPElement is created and a deep copy is made of the * domElement argument. The concrete type of the return value * will depend on the name of the domElement argument. If any * part of the tree rooted in domElement violates SOAP rules, a * SOAPException will be thrown. * * @param domElement - the Element to be copied. * * @return a new SOAPElement that is a copy of domElement. * * @exception SOAPException if there is an error in creating the * SOAPElement object * * @since 1.6, SAAJ 1.3 */ public SOAPElement createElement(Element domElement) throws SOAPException { throw new UnsupportedOperationException("createElement(org.w3c.dom.Element) must be overridden by all subclasses of SOAPFactory."); } /** * Creates a SOAPElement object initialized with the * given Name object. The concrete type of the return value * will depend on the name given to the new SOAPElement. For * instance, a new SOAPElement with the name * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a * SOAPEnvelope that supports SOAP 1.2 behavior to be created. * * @param name a Name object with the XML name for * the new element * * @return the new SOAPElement object that was * created * * @exception SOAPException if there is an error in creating the * SOAPElement object * @see SOAPFactory#createElement(javax.xml.namespace.QName) */ public abstract SOAPElement createElement(Name name) throws SOAPException; /** * Creates a SOAPElement object initialized with the * given QName object. The concrete type of the return value * will depend on the name given to the new SOAPElement. For * instance, a new SOAPElement with the name * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a * SOAPEnvelope that supports SOAP 1.2 behavior to be created. * * @param qname a QName object with the XML name for * the new element * * @return the new SOAPElement object that was * created * * @exception SOAPException if there is an error in creating the * SOAPElement object * @see SOAPFactory#createElement(Name) * @since 1.6, SAAJ 1.3 */ public SOAPElement createElement(QName qname) throws SOAPException { throw new UnsupportedOperationException("createElement(QName) must be overridden by all subclasses of SOAPFactory."); } /** * Creates a SOAPElement object initialized with the * given local name. * * @param localName a String giving the local name for * the new element * * @return the new SOAPElement object that was * created * * @exception SOAPException if there is an error in creating the * SOAPElement object */ public abstract SOAPElement createElement(String localName) throws SOAPException; /** * Creates a new SOAPElement object with the given * local name, prefix and uri. The concrete type of the return value * will depend on the name given to the new SOAPElement. For * instance, a new SOAPElement with the name * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a * SOAPEnvelope that supports SOAP 1.2 behavior to be created. * * @param localName a String giving the local name * for the new element * @param prefix the prefix for this SOAPElement * @param uri a String giving the URI of the * namespace to which the new element belongs * * @exception SOAPException if there is an error in creating the * SOAPElement object */ public abstract SOAPElement createElement( String localName, String prefix, String uri) throws SOAPException; /** * Creates a new Detail object which serves as a container * for DetailEntry objects. *

* This factory method creates Detail objects for use in * situations where it is not practical to use the SOAPFault * abstraction. * * @return a Detail object * @throws SOAPException if there is a SOAP error * @throws UnsupportedOperationException if the protocol specified * for the SOAPFactory was DYNAMIC_SOAP_PROTOCOL */ public abstract Detail createDetail() throws SOAPException; /** *Creates a new SOAPFault object initialized with the given reasonText * and faultCode *@param reasonText the ReasonText/FaultString for the fault *@param faultCode the FaultCode for the fault *@return a SOAPFault object *@throws SOAPException if there is a SOAP error *@since 1.6, SAAJ 1.3 */ public abstract SOAPFault createFault(String reasonText, QName faultCode) throws SOAPException; /** *Creates a new default SOAPFault object *@return a SOAPFault object *@throws SOAPException if there is a SOAP error *@since 1.6, SAAJ 1.3 */ public abstract SOAPFault createFault() throws SOAPException; /** * Creates a new Name object initialized with the * given local name, namespace prefix, and namespace URI. *

* This factory method creates Name objects for use in * situations where it is not practical to use the SOAPEnvelope * abstraction. * * @param localName a String giving the local name * @param prefix a String giving the prefix of the namespace * @param uri a String giving the URI of the namespace * @return a Name object initialized with the given * local name, namespace prefix, and namespace URI * @throws SOAPException if there is a SOAP error */ public abstract Name createName( String localName, String prefix, String uri) throws SOAPException; /** * Creates a new Name object initialized with the * given local name. *

* This factory method creates Name objects for use in * situations where it is not practical to use the SOAPEnvelope * abstraction. * * @param localName a String giving the local name * @return a Name object initialized with the given * local name * @throws SOAPException if there is a SOAP error */ public abstract Name createName(String localName) throws SOAPException; /** * Creates a new SOAPFactory object that is an instance of * the default implementation (SOAP 1.1), * * This method uses the following ordered lookup procedure to determine the SOAPFactory implementation class to load: *

* * @return a new instance of a SOAPFactory * * @exception SOAPException if there was an error creating the * default SOAPFactory * @see SAAJMetaFactory */ public static SOAPFactory newInstance() throws SOAPException { try { SOAPFactory factory = (SOAPFactory) FactoryFinder.find( SOAP_FACTORY_PROPERTY, DEFAULT_SOAP_FACTORY, false); if (factory != null) return factory; return newInstance(SOAPConstants.SOAP_1_1_PROTOCOL); } catch (Exception ex) { throw new SOAPException( "Unable to create SOAP Factory: " + ex.getMessage()); } } /** * Creates a new SOAPFactory object that is an instance of * the specified implementation, this method uses the SAAJMetaFactory to * locate the implementation class and create the SOAPFactory instance. * * @return a new instance of a SOAPFactory * * @param protocol a string constant representing the protocol of the * specified SOAP factory implementation. May be * either DYNAMIC_SOAP_PROTOCOL, * DEFAULT_SOAP_PROTOCOL (which is the same * as) SOAP_1_1_PROTOCOL, or * SOAP_1_2_PROTOCOL. * * @exception SOAPException if there was an error creating the * specified SOAPFactory * @see SAAJMetaFactory * @since 1.6, SAAJ 1.3 */ public static SOAPFactory newInstance(String protocol) throws SOAPException { return SAAJMetaFactory.getInstance().newSOAPFactory(protocol); } }