|
Sun Java(tm) System Message Queue v3.6 |
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
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
JavaTM 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(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 |
public ProviderMetaData getMetaData()
throws JAXMException
ProviderMetaData object that contains
information about the messaging provider to which this
ProviderConnection object is connected.
ProviderMetaData object with information
about the messaging provider
JAXMException - if there is a problem getting the
ProviderMetaData objectProviderMetaData
public void close()
throws JAXMException
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.
JAXMException - if a JAXM error occurs while closing
the connection.
public MessageFactory createMessageFactory(String profile)
throws JAXMException
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.
profile - a string that represents a particular JAXM
profile in use. An example of a JAXM profile is:
"ebxml".
MessageFactory object that will create
SOAPMessage objects for the given profile
JAXMException - if the JAXM infrastructure encounters
an error, for example, if the endpoint
that is being used is not compatible
with the specified profile
public void send(SOAPMessage message)
throws JAXMException
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.
message - the SOAPMessage object that is to be
sent asynchronously over this ProviderConnection object
JAXMException - if a JAXM transmission error occurs
|
Sun Java(tm) System Message Queue v3.6 |
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||