javax.xml.soap

## Class SOAPFactory

- java.lang.Object
- - javax.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 `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.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SOAPFactory()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract Detail` | `createDetail()` Creates a new `Detail` object which serves as a container for `DetailEntry` objects.
    `SOAPElement` | `createElement(Element domElement)` Creates a `SOAPElement` object from an existing DOM `Element`.
    `abstract SOAPElement` | `createElement(Name name)` Creates a `SOAPElement` object initialized with the given `Name` object.
    `SOAPElement` | `createElement(QName qname)` Creates a `SOAPElement` object initialized with the given `QName` object.
    `abstract SOAPElement` | `createElement(String localName)` Creates a `SOAPElement` object initialized with the given local name.
    `abstract SOAPElement` | `createElement(String localName, String prefix, String uri)` Creates a new `SOAPElement` object with the given local name, prefix and uri.
    `abstract SOAPFault` | `createFault()` Creates a new default `SOAPFault` object
    `abstract SOAPFault` | `createFault(String reasonText, QName faultCode)` Creates a new `SOAPFault` object initialized with the given `reasonText` and `faultCode`
    `abstract Name` | `createName(String localName)` Creates a new `Name` object initialized with the given local name.
    `abstract Name` | `createName(String localName, String prefix, String uri)` Creates a new `Name` object initialized with the given local name, namespace prefix, and namespace URI.
    `static SOAPFactory` | `newInstance()` 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.
    `static SOAPFactory` | `newInstance(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.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### SOAPFactory

          public SOAPFactory()

  - ### Method Detail

    - #### createElement

          public SOAPElement createElement(Element domElement)
                                    throws SOAPException

      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.
      Parameters:
        `domElement` - - the `Element` to be copied.
      Returns:
        a new `SOAPElement` that is a copy of `domElement`.
      Throws:
        `SOAPException` - if there is an error in creating the `SOAPElement` object
      Since:
        SAAJ 1.3

    - #### createElement

          public abstract SOAPElement createElement(Name name)
                                             throws SOAPException

      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.
      Parameters:
        `name` - a `Name` object with the XML name for the new element
      Returns:
        the new `SOAPElement` object that was created
      Throws:
        `SOAPException` - if there is an error in creating the `SOAPElement` object
      See Also:
        `createElement(javax.xml.namespace.QName)`

    - #### createElement

          public SOAPElement createElement(QName qname)
                                    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.
      Parameters:
        `qname` - a `QName` object with the XML name for the new element
      Returns:
        the new `SOAPElement` object that was created
      Throws:
        `SOAPException` - if there is an error in creating the `SOAPElement` object
      Since:
        SAAJ 1.3
      See Also:
        `createElement(Name)`

    - #### createElement

          public abstract SOAPElement createElement(String localName)
                                             throws SOAPException

      Creates a `SOAPElement` object initialized with the given local name.
      Parameters:
        `localName` - a `String` giving the local name for the new element
      Returns:
        the new `SOAPElement` object that was created
      Throws:
        `SOAPException` - if there is an error in creating the `SOAPElement` object

    - #### createElement

          public abstract SOAPElement createElement(String localName,
                                  String prefix,
                                  String uri)
                                             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.
      Parameters:
        `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

    - #### createDetail

          public abstract Detail createDetail()
                                       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.

      Returns:
        a `Detail` object
      Throws:
        `SOAPException` - if there is a SOAP error
        `UnsupportedOperationException` - if the protocol specified for the SOAPFactory was `DYNAMIC_SOAP_PROTOCOL`

    - #### createFault

          public abstract SOAPFault createFault(String reasonText,
                              QName faultCode)
                                         throws SOAPException

      Creates a new `SOAPFault` object initialized with the given `reasonText` and `faultCode`
      Parameters:
        `reasonText` - the ReasonText/FaultString for the fault
        `faultCode` - the FaultCode for the fault
      Returns:
        a `SOAPFault` object
      Throws:
        `SOAPException` - if there is a SOAP error
      Since:
        SAAJ 1.3

    - #### createFault

          public abstract SOAPFault createFault()
                                         throws SOAPException

      Creates a new default `SOAPFault` object
      Returns:
        a `SOAPFault` object
      Throws:
        `SOAPException` - if there is a SOAP error
      Since:
        SAAJ 1.3

    - #### createName

          public abstract Name createName(String localName,
                        String prefix,
                        String uri)
                                   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.

      Parameters:
        `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
      Returns:
        a `Name` object initialized with the given local name, namespace prefix, and namespace URI
      Throws:
        `SOAPException` - if there is a SOAP error

    - #### createName

          public abstract Name createName(String localName)
                                   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.

      Parameters:
        `localName` - a `String` giving the local name
      Returns:
        a `Name` object initialized with the given local name
      Throws:
        `SOAPException` - if there is a SOAP error

    - #### newInstance

          public static SOAPFactory newInstance()
                                         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.
      Returns:
        a new instance of a `SOAPFactory`
      Throws:
        `SOAPException` - if there was an error creating the default `SOAPFactory`
      See Also:
        `SAAJMetaFactory`

    - #### newInstance

          public static SOAPFactory newInstance(String protocol)
                                         throws SOAPException

      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.
      Parameters:
        `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`
      Throws:
        `SOAPException` - if there was an error creating the specified `SOAPFactory`
      Since:
        SAAJ 1.3
      See Also:
        `SAAJMetaFactory`

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.