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.
