Module java.xml.soap
Package 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.

Since:
  1.6

### Constructor Summary

Constructors
`SOAPFactory​()`

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
`abstract Detail` `createDetail​()` Creates a new `Detail` object which serves as a container for `DetailEntry` objects.
`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.
`SOAPElement` `createElement​(QName qname)` Creates a `SOAPElement` object initialized with the given `QName` object.
`abstract SOAPElement` `createElement​(Name name)` Creates a `SOAPElement` object initialized with the given `Name` object.
`SOAPElement` `createElement​(Element domElement)` Creates a `SOAPElement` object from an existing DOM `Element`.
`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).
`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:
  1.6, 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:
  1.6, 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
Returns:
  the new `SOAPElement` object that was created
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:
  1.6, 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:
  1.6, 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 lookup procedure specified in `javax.xml.soap` to locate and load the `SOAPFactory` 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:
  1.6, SAAJ 1.3
See Also:
  `SAAJMetaFactory`