public interface ProviderConnection {
// Public Instance Methods
public abstract void close( ) throws JAXMException;
public abstract javax.xml.soap.MessageFactory createMessageFactory(String profile) throws JAXMException;
public abstract ProviderMetaData getMetaData( ) throws JAXMException;
public abstract void send(javax.xml.soap.SOAPMessage message) throws JAXMException;
}
A ProviderConnection object represents a
connection path between a JAXM client and a JAXM provider. An
instance of this class can be obtained using the
createConnection( ) method of
ProviderConnectionFactory, as described in the
reference section for that class. Here's a typical
example:
ProviderConnectionFactory pcf = ProviderConnectionFactory.newInstance( );
ProviderConnection conn = pcf.createConnection( );
All JAXM clients work with a JAXM message profile, which constructs
SOAP messages according to agreed rules. A JAXM client can use the
getMetaData( ) method to obtain a
ProviderMetaData object that can be used to get
the names of the profiles that the provider supports. In practice,
however, a JAXM client has to be written with knowledge of the
classes that implement a particular profile; therefore, this
mechanism will probably only be used to verify that the required
profile is available.
The createMessageFactory( ) method returns an
object that can create messages formed according to the rules of the
profile whose name is provided as its argument. The set of profiles
supported by a provider and the names by which they are known are
implementation-dependent. The reference implementation recognizes the
names soaprp and ebxml. The
following code returns a message factory that knows how to build SOAP
messages according to the rules in the WS-Routing (formerly SOAP-RP)
specification:
MessageFactory factory = conn.createMessageFactory("soaprp");
A JAXMException is thrown if the provider does not
support the requested profile. Refer to the reference section for the
javax.xml.soap package for a description of the
MessageFactory class.
Having constructed a SOAP message, a client forwards it to its local
provider using the send( ) method, which requires
only the message itself as an argument. Unlike the send(
) method of the SAAJ SOAPConnection
class, this method does not have an explicit destination address
argument. Instead, the message is expected to specify the intended
recipient using an address element that is specific to the profile
according to which it was constructed. Furthermore, the address is
usually not a fixed transport address (such as a URL). More likely,
it is a URI that is used as a key to a configuration table in the
provider where the URL of the JAXM provider local to the message
recipient is held.
The close( ) method is used to release the
ProviderConnection object when it is no longer
required.
