FileDocCategorySizeDatePackage
SOAPFactory.javaAPI DocJava SE 6 API12348Tue Jun 10 00:27:10 BST 2008javax.xml.soap

SOAPFactory

public abstract class SOAPFactory extends Object
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.

Fields Summary
private static final String
SOAP_FACTORY_PROPERTY
A constant representing the property used to lookup the name of a SOAPFactory implementation class.
Constructors Summary
Methods Summary
public abstract javax.xml.soap.DetailcreateDetail()
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 javax.xml.soap.SOAPElementcreateElement(org.w3c.dom.Element domElement)
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


                                                                                                                                                 
          
        throw new UnsupportedOperationException("createElement(org.w3c.dom.Element) must be overridden by all subclasses of SOAPFactory.");
    
public abstract javax.xml.soap.SOAPElementcreateElement(javax.xml.soap.Name name)
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 javax.xml.soap.SOAPElementcreateElement(javax.xml.namespace.QName qname)
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

        throw new UnsupportedOperationException("createElement(QName) must be overridden by all subclasses of SOAPFactory.");
    
public abstract javax.xml.soap.SOAPElementcreateElement(java.lang.String localName)
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 javax.xml.soap.SOAPElementcreateElement(java.lang.String localName, java.lang.String prefix, java.lang.String uri)
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 javax.xml.soap.SOAPFaultcreateFault(java.lang.String reasonText, javax.xml.namespace.QName faultCode)
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 javax.xml.soap.SOAPFaultcreateFault()
Creates a new default SOAPFault object

return
a SOAPFault object
throws
SOAPException if there is a SOAP error
since
SAAJ 1.3

public abstract javax.xml.soap.NamecreateName(java.lang.String localName)
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 javax.xml.soap.NamecreateName(java.lang.String localName, java.lang.String prefix, java.lang.String uri)
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 static javax.xml.soap.SOAPFactorynewInstance()
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

        try {
            SOAPFactory factory = (SOAPFactory) FactoryFinder.find(SOAP_FACTORY_PROPERTY);
            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());
        }

    
public static javax.xml.soap.SOAPFactorynewInstance(java.lang.String protocol)
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

            return SAAJMetaFactory.getInstance().newSOAPFactory(protocol);