SOAPConnectionFactory

   

---

SOAPConnection

javax.xml.soap

---

SAAJ 1.1; JWSDP 1.0, J2EE 1.4

 public abstract class SOAPConnection {  // Public Constructors  public SOAPConnection(  );  // Public Instance Methods  public abstract SOAPMessage call(SOAPMessage   request   , Object to)     throws SOAPException;      public abstract void close(  ) throws SOAPException;  } 

SOAPConnection is an object that can be used to send SOAP messages. Despite its name , it does not represent a connection in the traditional sense, since it does not have a fixed association with a peer object. Instead, it is better thought of as an access point that can be used to send any number of individually addressed SOAP messages to arbitrary receivers.

To obtain a SOAPConnection , you need to use a SOAPConnectionFactory :

 SOAPConnectionFactory factory = SOAPConnectionFactory.newInstance; SOAPConnection conn = factory.createConnection; 

Both SOAPConnectionFactory and SOAPConnection are abstract classes, concrete instances of which are provided by your SAAJ implementation. The fact that the SOAPConnectionFactory newInstance( ) method searches for a suitable implementation class (as described in its reference section in this chapter) means that you can plug in different SAAJ implementations without changing your application code. When a SOAPConnection is no longer required, it should be released by calling its close( ) method.

The call( ) method takes a SOAPMessage object, serializes it into XML, and sends it to the destination given by its to argument. This argument is declared to be of type Object , which allows implementations to support various different forms of destination addresses. At a minimum, the following types must be supported:

java.net.URL

This is the simplest case: the URL directly specifies the location of the message recipient.

java.lang.String

When a string is supplied, it is expected to be the string representation of a valid URL.

javax.xml.messaging.URLEndpoint

This is a special case that is supported for compatibility with the JAXM API. The URLEndpoint is a simple wrapper for a URL, which is obtained by calling its getURL( ) method and treated as the message destination. This form of address is available only on systems that have JAXM installed. Note that JAXM is not part of the J2EE 1.4 platform; therefore, it cannot be assumed to be universally available.

Once the message is sent, the call( ) method blocks until a reply is received. The reply is unmarshalled from XML into a SOAPMessage , which is then returned to the caller. call( ) therefore represents a synchronous message exchange between a client and a server. SAAJ does not support asynchronous operation; if you need this functionality, you may either simulate it by starting a new thread to deliver a message, or by using JAXM if it is available.

Returned By

SOAPConnectionFactory.createConnection( )

---