geronimo-saaj_1.3_spec/src/main/java/javax/xml/soap/SOAPFactory.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements. See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership. The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied. See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package javax.xml.soap;


/**
 * <code>SOAPFactory</code> is a factory for creating various objects that exist in the SOAP XML
 * tree.
 * <p/>
 * <code>SOAPFactory</code> 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 <code>SOAPHeaderElement</code> or
 * <code>SOAPBodyElement</code> or <code>SOAPEnvelope</code>.
 * <p/>
 * <code>SOAPFactory</code> also has methods to create <code>javax.xml.soap.Detail</code> objects as
 * well as <code>java.xml.soap.Name</code> objects.
 */
public abstract class SOAPFactory {

    public SOAPFactory() {
    }

    /**
     * Create a <code>SOAPElement</code> object initialized with the given <code>Name</code>
     * object.
     *
     * @param name a <code>Name</code> object with the XML name for the new element
     * @return the new <code>SOAPElement</code> object that was created
     * @throws SOAPException if there is an error in creating the <code>SOAPElement</code> object
     */
    public abstract SOAPElement createElement(Name name) throws SOAPException;

    /**
     * Create a <code>SOAPElement</code> object initialized with the given local name.
     *
     * @param localName a <code>String</code> giving the local name for the new element
     * @return the new <code>SOAPElement</code> object that was created
     * @throws SOAPException if there is an error in creating the <code>SOAPElement</code> object
     */
    public abstract SOAPElement createElement(String localName) throws SOAPException;

    /**
     * Create a new <code>SOAPElement</code> object with the given local name, prefix and uri.
     *
     * @param localName a <code>String</code> giving the local name for the new element
     * @param prefix    the prefix for this <code>SOAPElement</code>
     * @param uri       a <code>String</code> giving the URI of the namespace to which the new
     *                  element belongs
     * @return the new <code>SOAPElement</code> object that was created
     * @throws SOAPException if there is an error in creating the <code>SOAPElement</code> object
     */
    public abstract SOAPElement createElement(String localName,
                                              String prefix,
                                              String uri)
            throws SOAPException;

    /**
     * Creates a new <code>Detail</code> object which serves as a container for
     * <code>DetailEntry</code> objects.
     * <p/>
     * This factory method creates <code>Detail</code> objects for use in situations where it is not
     * practical to use the <code>SOAPFault</code> abstraction.
     *
     * @return a <code>Detail</code> object
     * @throws SOAPException if there is a SOAP error
     */
    public abstract Detail createDetail() throws SOAPException;

    /**
     * Creates a new <code>Name</code> object initialized with the given local name, namespace
     * prefix, and namespace URI.
     * <p/>
     * This factory method creates <code>Name</code> objects for use in situations where it is not
     * practical to use the <code>SOAPEnvelope</code> abstraction.
     *
     * @param localName a <code>String</code> giving the local name
     * @param prefix    a <code>String</code> giving the prefix of the namespace
     * @param uri       a <code>String</code> giving the URI of the namespace
     * @return a <code>Name</code> 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 <code>Name</code> object initialized with the given local name.
     * <p/>
     * This factory method creates <code>Name</code> objects for use in situations where it is not
     * practical to use the <code>SOAPEnvelope</code> abstraction.
     *
     * @param localName a <code>String</code> giving the local name
     * @return a <code>Name</code> 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 instance of <code>SOAPFactory</code>.
     *
     * @return a new instance of a <code>SOAPFactory</code>
     * @throws SOAPException if there was an error creating the default <code>SOAPFactory</code>
     */
    public static SOAPFactory newInstance() throws SOAPException {
        try {
            SOAPFactory factory = (SOAPFactory)FactoryFinder.find(SOAPFactory.class, null);
            if (factory == null) {
                factory = newInstance(SOAPConstants.SOAP_1_1_PROTOCOL);
            }
            return factory;
        } catch (Exception exception) {
            throw new SOAPException("Unable to create SOAPFactory: " + exception.getMessage(), exception);
        }
    }


    /**
     * 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.
     *
     * @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. Returns: a
     *                 new instance of a SOAPFactory
     * @return javax.xml.soap.SOAPFactory
     * @throws SOAPException - if there is an error creating the specified SOAPFactory
     * @see <CODE>SAAJMetaFactory</CODE>
     */
    public static SOAPFactory newInstance(String protocol) throws SOAPException {
        return SAAJMetaFactory.getInstance().newSOAPFactory(protocol);
    }


    /**
     * 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.
     * @throws SOAPException - if there is an error in creating the SOAPElement object
     * @see SOAPFactoryImpl
     * @since SAAJ 1.3
     */
    public SOAPElement createElement(org.w3c.dom.Element element)
            throws SOAPException {
        //see SOAPFactoryImpl
        return null;
    }


    /**
     * 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} 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
     * @throws SOAPException - if there is an error in creating the SOAPElement object
     * @see SOAPFactoryImpl
     */
    public SOAPElement createElement(javax.xml.namespace.QName qname)
            throws SOAPException {
        return null;
    }

    public abstract SOAPFault createFault()
            throws SOAPException;

    public abstract SOAPFault createFault(java.lang.String reasonText,
                                          javax.xml.namespace.QName faultCode)
            throws SOAPException;
}