public interface ProviderConnection
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.
Modifier and Type | Method and Description |
---|---|
void |
close()
Closes this
ProviderConnection object, freeing its resources and making it immediately available for
garbage collection. |
javax.xml.soap.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(javax.xml.soap.SOAPMessage message)
Sends the given
SOAPMessage object and returns immediately after handing the message over to the
messaging provider. |
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 providerJAXMException
- if there is a problem getting the ProviderMetaData
objectProviderMetaData
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.javax.xml.soap.MessageFactory createMessageFactory(java.lang.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
profileJAXMException
- if the JAXM infrastructure encounters an error, for example, if the endpoint that is being
used is not compatible with the specified profilevoid send(javax.xml.soap.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
objectJAXMException
- if a JAXM transmission error occursCopyright (c) 2010, 2017 Oracle and/or its affiliates. All rights reserved.