javax.xml.messaging
Interface ProviderConnection

public interface ProviderConnection

A client's active connection to its messaging provider.

A ProviderConnection object is created using a ProviderConnectionFactory object, which is configured so that the connections it creates will be to a particular messaging provider. To create a connection, a client first needs to obtain an instance of the ProviderConnectionFactory class that creates connections to the desired messaging provider. The client then calls the createConnection method on it.

The information necessary to set up a ProviderConnectionFactory object that creates connections to a particular messaging provider is supplied at deployment time. Typically an instance of ProviderConnectionFactory will be bound to a logical name in a naming service. Later the client can do a lookup on the logical name to retrieve an instance of the ProviderConnectionFactory class that produces connections to its messaging provider.

The following code fragment is an example of a client doing a lookup of a ProviderConnectionFactory object and then using it to create a connection. The first two lines in this example use the Java^TM Naming and Directory Interface (JNDI) to create a context, which is then used to do the lookup. The argument provided to the lookup method is the logical name that was previously associated with the desired messaging provider. The lookup method returns a Java Object, which needs to be cast to a ProviderConnectionFactory object before it can be used to create a connection. In the following code fragment, the resulting ProviderConnection object is a connection to the messaging provider that is associated with the logical name "ProviderXYZ".

    Context ctx = new InitialContext();
    ProviderConnectionFactory pcf = (ProviderConnectionFactory)ctx.lookup("ProviderXYZ");
    ProviderConnection con = pcf.createConnection();
 

After the client has obtained a connection to its messaging provider, it can use that connection to create one or more MessageFactory objects, which can then be used to create SOAPMessage objects. Messages are delivered to an endpoint using the ProviderConnection method send.

The messaging provider maintains a list of Endpoint objects, which is established at deployment time as part of configuring the messaging provider. When a client uses a messaging provider to send messages, it can send messages only to those parties represented by Endpoint objects in its messaging provider's list. This is true because the messaging provider maps the URI for each Endpoint object to a URL.

Note that it is possible for a client to send a message without using a messaging provider. In this case, the client uses a SOAPConnection object to send point-to-point messages via the method call. This method takes an Endpoint object (actually a URLEndpoint object) that specifies the URL where the message is to be sent. See SOAPConnection and URLEndpoint for more information.

Typically, because clients have one messaging provider, they will do all their messaging with a single ProviderConnection object. It is possible, however, for a sophisticated application to use multiple connections.

Generally, a container is configured with a listener component at deployment time using an implementation-specific mechanism. A client running in such a container uses a OnewayListener object to receive messages asynchronously. In this scenario, messages are sent via the ProviderConnection method send. A client running in a container that wants to receive synchronous messages uses a ReqRespListener object. A ReqRespListener object receives messages sent via the SOAPConnection method call.

Due to the authentication and communication setup done when a ProviderConnection object is created, it is a relatively heavy-weight object. Therefore, a client should close its connection as soon as it is done using it.

JAXM objects created using one ProviderConnection object cannot be used with a different ProviderConnection object.

Method Summary

void	close() Closes this ProviderConnection object, freeing its resources and making it immediately available for garbage collection.
MessageFactory	createMessageFactory(java.lang.String profile) Creates a MessageFactory object that will produce SOAPMessage objects for the given profile.
ProviderMetaData	getMetaData() Retrieves the ProviderMetaData object that contains information about the messaging provider to which this ProviderConnection object is connected.
void	send(SOAPMessage message) Sends the given SOAPMessage object and returns immediately after handing the message over to the messaging provider.

Method Detail

getMetaData

public ProviderMetaData getMetaData()
                             throws JAXMException

Retrieves the ProviderMetaData object that contains information about the messaging provider to which this ProviderConnection object is connected.

Returns:

the ProviderMetaData object with information about the messaging provider

Throws:

JAXMException - if there is a problem getting the ProviderMetaData object

See Also:

ProviderMetaData

close

public void close()
           throws JAXMException

Closes this ProviderConnection object, freeing its resources and making it immediately available for garbage collection. Since a provider typically allocates significant resources outside the JVM on behalf of a connection, clients should close connections when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough.

Throws:

JAXMException - if a JAXM error occurs while closing the connection.

createMessageFactory

public MessageFactory createMessageFactory(java.lang.String profile)
                                    throws JAXMException

Creates a MessageFactory object that will produce SOAPMessage objects for the given profile. The MessageFactory object that is returned can create instances of SOAPMessage subclasses as appropriate for the given profile.

Parameters:

profile - a string that represents a particular JAXM profile in use. An example of a JAXM profile is: "ebxml".

Returns:

a new MessageFactory object that will create SOAPMessage objects for the given profile

Throws:

JAXMException - if the JAXM infrastructure encounters an error, for example, if the endpoint that is being used is not compatible with the specified profile

send

public void send(SOAPMessage message)
          throws JAXMException

Sends the given SOAPMessage object and returns immediately after handing the message over to the messaging provider. No assumptions can be made regarding the ultimate success or failure of message delivery at the time this method returns.

Parameters:

message - the SOAPMessage object that is to be sent asynchronously over this ProviderConnection object

Throws:

JAXMException - if a JAXM transmission error occurs