javax.xml.soap.SOAPFactory Maven / Gradle / Ivy
/*
* The contents of this file are subject to the terms
* of the Common Development and Distribution License
* (the License). You may not use this file except in
* compliance with the License.
*
* You can obtain a copy of the license at
* http://glassfish.java.net/public/CDDL+GPL_1_1.html.
* See the License for the specific language governing
* permissions and limitations under the License.
*
* When distributing Covered Code, include this CDDL
* Header Notice in each file and include the License file
* at http://glassfish.java.net/public/CDDL+GPL_1_1.html.
* If applicable, add the following below the CDDL Header,
* with the fields enclosed by brackets [] replaced by
* you own identifying information:
* "Portions Copyrighted [year] [name of copyright owner]"
*
* Copyright (c) 2004-2013 Oracle and/or its affiliates. All rights reserved.
*/
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.
*
*/
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 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 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 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 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:
*
* - Use the javax.xml.soap.SOAPFactory system property.
*
- Use the properties file "lib/jaxm.properties" in the JRE directory. This configuration file is in standard
* java.util.Properties format and contains the fully qualified name of the implementation class with the key being the
* system property defined above.
*
- Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API
* will look for a classname in the file META-INF/services/javax.xml.soap.SOAPFactory in jars available to the runtime.
*
- Use the SAAJMetaFactory instance to locate the SOAPFactory implementation class.
*
*
* @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 SAAJ 1.3
*/
public static SOAPFactory newInstance(String protocol)
throws SOAPException {
return SAAJMetaFactory.getInstance().newSOAPFactory(protocol);
}
}