https://openjdk.java.net/ 
/*
 * Copyright (c) 2004, 2017, 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 SOAPHeaderElement or SOAPBodyElement or SOAPEnvelope or other SOAPElement objects. SOAPFactory also has methods to create javax.xml.soap.Detail objects as well as java.xml.soap.Name objects. 
Since:1.6
/**
 * {@code SOAPFactory} is a factory for creating various objects
 * that exist in the SOAP XML tree.

 * {@code 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.
 *
 * {@code SOAPFactory} also has methods to create
 * {@code javax.xml.soap.Detail} objects as well as
 * {@code java.xml.soap.Name} objects.
 *
 * @since 1.6
 */
public abstract class SOAPFactory {

    
Class name of default SOAPFactory implementation. 
/**
     * Class name of default {@code SOAPFactory} implementation.
     */
    private 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. 
Params:
  • domElement – - the Element to be copied.
Throws:
  • SOAPException – if there is an error in creating the SOAPElement object
Returns:a new SOAPElement that is a copy of domElement.
Since:1.6, SAAJ 1.3
/**
     * Creates a {@code SOAPElement} object from an existing DOM
     * {@code Element}. If the DOM {@code Element} that is passed in
     * as an argument is already a {@code SOAPElement} then this method
     * must return it unmodified without any further work. Otherwise, a new
     * {@code SOAPElement} is created and a deep copy is made of the
     * {@code domElement} argument. The concrete type of the return value
     * will depend on the name of the {@code domElement} argument. If any
     * part of the tree rooted in {@code domElement} violates SOAP rules, a
     * {@code SOAPException} will be thrown.
     *
     * @param domElement - the {@code Element} to be copied.
     *
     * @return a new {@code SOAPElement} that is a copy of {@code domElement}.
     *
     * @exception SOAPException if there is an error in creating the
     *            {@code 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. 
Params:
  • name – a Name object with the XML name for the new element
Throws:
  • SOAPException – if there is an error in creating the SOAPElement object
See Also:
Returns:the new SOAPElement object that was created
/**
     * Creates a {@code SOAPElement} object initialized with the
     * given {@code Name} object. The concrete type of the return value
     * will depend on the name given to the new {@code SOAPElement}. For
     * instance, a new {@code SOAPElement} with the name
     * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a
     * {@code SOAPEnvelope} that supports SOAP 1.2 behavior to be created.
     *
     * @param name a {@code Name} object with the XML name for
     *             the new element
     *
     * @return the new {@code SOAPElement} object that was
     *         created
     *
     * @exception SOAPException if there is an error in creating the
     *            {@code 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. 
Params:
  • qname – a QName object with the XML name for the new element
Throws:
  • SOAPException – if there is an error in creating the SOAPElement object
See Also:
Returns:the new SOAPElement object that was created
Since:1.6, SAAJ 1.3
/**
     * Creates a {@code SOAPElement} object initialized with the
     * given {@code QName} object. The concrete type of the return value
     * will depend on the name given to the new {@code SOAPElement}. For
     * instance, a new {@code SOAPElement} with the name
     * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a
     * {@code SOAPEnvelope} that supports SOAP 1.2 behavior to be created.
     *
     * @param qname a {@code QName} object with the XML name for
     *             the new element
     *
     * @return the new {@code SOAPElement} object that was
     *         created
     *
     * @exception SOAPException if there is an error in creating the
     *            {@code 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. 
Params:
  • localName – a String giving the local name for the new element
Throws:
  • SOAPException – if there is an error in creating the SOAPElement object
Returns:the new SOAPElement object that was created
/**
     * Creates a {@code SOAPElement} object initialized with the
     * given local name.
     *
     * @param localName a {@code String} giving the local name for
     *             the new element
     *
     * @return the new {@code SOAPElement} object that was
     *         created
     *
     * @exception SOAPException if there is an error in creating the
     *            {@code 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. 
Params:
  • localName – a String giving the local name for the new element
  • prefix – the prefix for this SOAPElement
  • uri – a String giving the URI of the namespace to which the new element belongs
Throws:
  • SOAPException – if there is an error in creating the SOAPElement object
Returns:the new SOAPElement object that was created
/**
     * Creates a new {@code 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 {@code SOAPElement}. For
     * instance, a new {@code SOAPElement} with the name
     * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a
     * {@code SOAPEnvelope} that supports SOAP 1.2 behavior to be created.
     *
     * @param localName a {@code String} giving the local name
     *                  for the new element
     * @param prefix the prefix for this {@code SOAPElement}
     * @param uri a {@code String} giving the URI of the
     *            namespace to which the new element belongs
     * @return the new {@code SOAPElement} object that was
     *         created
     *
     * @exception SOAPException if there is an error in creating the
     *            {@code 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. 
Throws:
Returns:a Detail object
/**
     * Creates a new {@code Detail} object which serves as a container
     * for {@code DetailEntry} objects.
     * <P>
     * This factory method creates {@code Detail} objects for use in
     * situations where it is not practical to use the {@code SOAPFault}
     * abstraction.
     *
     * @return a {@code Detail} object
     * @throws SOAPException if there is a SOAP error
     * @throws UnsupportedOperationException if the protocol specified
     *         for the SOAPFactory was {@code DYNAMIC_SOAP_PROTOCOL}
     */
    public abstract Detail createDetail() throws SOAPException;

    
Creates a new SOAPFault object initialized with the given reasonText and faultCode 
Params:
  • reasonText – the ReasonText/FaultString for the fault
  • faultCode – the FaultCode for the fault
Throws:
Returns:a SOAPFault object
Since:1.6, SAAJ 1.3
/**
     *Creates a new {@code SOAPFault} object initialized with the given {@code reasonText}
     *  and {@code faultCode}
     *@param reasonText the ReasonText/FaultString for the fault
     *@param faultCode the FaultCode for the fault
     *@return a {@code 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 
Throws:
Returns:a SOAPFault object
Since:1.6, SAAJ 1.3
/**
     *Creates a new default {@code SOAPFault} object
     *@return a {@code 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. 
Params:
  • localName – a String giving the local name
  • prefix – a String giving the prefix of the namespace
  • uri – a String giving the URI of the namespace
Throws:
Returns:a Name object initialized with the given local name, namespace prefix, and namespace URI
/**
     * Creates a new {@code Name} object initialized with the
     * given local name, namespace prefix, and namespace URI.
     * <P>
     * This factory method creates {@code Name} objects for use in
     * situations where it is not practical to use the {@code SOAPEnvelope}
     * abstraction.
     *
     * @param localName a {@code String} giving the local name
     * @param prefix a {@code String} giving the prefix of the namespace
     * @param uri a {@code String} giving the URI of the namespace
     * @return a {@code 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. 
Params:
  • localName – a String giving the local name
Throws:
Returns:a Name object initialized with the given local name
/**
     * Creates a new {@code Name} object initialized with the
     * given local name.
     * <P>
     * This factory method creates {@code Name} objects for use in
     * situations where it is not practical to use the {@code SOAPEnvelope}
     * abstraction.
     *
     * @param localName a {@code String} giving the local name
     * @return a {@code 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 lookup procedure specified in soap to locate and load the SOAPFactory class. 
Throws:
  • SOAPException – if there was an error creating the default SOAPFactory
See Also:
Returns:a new instance of a SOAPFactory
/**
     * Creates a new {@code SOAPFactory} object that is an instance of
     * the default implementation (SOAP 1.1).
     *
     * This method uses the lookup procedure specified in {@link javax.xml.soap} to locate and load the
     * {@link javax.xml.soap.SOAPFactory} class.
     *
     * @return a new instance of a {@code SOAPFactory}
     *
     * @exception SOAPException if there was an error creating the
     *            default {@code SOAPFactory}
     * @see SAAJMetaFactory
     */
    public static SOAPFactory newInstance()
        throws SOAPException
    {
        try {
            SOAPFactory factory = FactoryFinder.find(
                    SOAPFactory.class,
                    DEFAULT_SOAP_FACTORY,
                    false);
            if (factory != null) return factory;

            // leave it on SAAJMetaFactory
            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. 
Params:
  • 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.
Throws:
  • SOAPException – if there was an error creating the specified SOAPFactory
See Also:
Returns:a new instance of a SOAPFactory
Since:1.6, SAAJ 1.3
/**
     * Creates a new {@code 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 {@code SOAPFactory}
     *
     * @param protocol  a string constant representing the protocol of the
     *                   specified SOAP factory implementation. May be
     *                   either {@code DYNAMIC_SOAP_PROTOCOL},
     *                   {@code DEFAULT_SOAP_PROTOCOL} (which is the same
     *                   as) {@code SOAP_1_1_PROTOCOL}, or
     *                   {@code SOAP_1_2_PROTOCOL}.
     *
     * @exception SOAPException if there was an error creating the
     *            specified {@code SOAPFactory}
     * @see SAAJMetaFactory
     * @since 1.6, SAAJ 1.3
     */
    public static SOAPFactory newInstance(String protocol)
        throws SOAPException {
            return SAAJMetaFactory.getInstance().newSOAPFactory(protocol);
    }
}