Interface ProviderConnection
-
@Deprecated public interface ProviderConnectionDeprecated.since 6.2, will be removed without replacementA client's active connection to its messaging provider.A
ProviderConnectionobject is created using aProviderConnectionFactoryobject, 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 theProviderConnectionFactoryclass that creates connections to the desired messaging provider. The client then calls thecreateConnectionmethod on it.The information necessary to set up a
ProviderConnectionFactoryobject that creates connections to a particular messaging provider is supplied at deployment time. Typically an instance ofProviderConnectionFactorywill 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 theProviderConnectionFactoryclass that produces connections to its messaging provider.The following code fragment is an example of a client doing a lookup of a
ProviderConnectionFactoryobject 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 thelookupmethod is the logical name that was previously associated with the desired messaging provider. Thelookupmethod returns a JavaObject, which needs to be cast to aProviderConnectionFactoryobject before it can be used to create a connection. In the following code fragment, the resultingProviderConnectionobject 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
MessageFactoryobjects, which can then be used to createSOAPMessageobjects. Messages are delivered to an endpoint using theProviderConnectionmethodsend.The messaging provider maintains a list of
Endpointobjects, 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 byEndpointobjects in its messaging provider's list. This is true because the messaging provider maps the URI for eachEndpointobject 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
SOAPConnectionobject to send point-to-point messages via the methodcall. This method takes anEndpointobject (actually aURLEndpointobject) that specifies the URL where the message is to be sent. SeeSOAPConnectionandURLEndpointfor more information.Typically, because clients have one messaging provider, they will do all their messaging with a single
ProviderConnectionobject. 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
OnewayListenerobject to receive messages asynchronously. In this scenario, messages are sent via theProviderConnectionmethodsend. A client running in a container that wants to receive synchronous messages uses aReqRespListenerobject. AReqRespListenerobject receives messages sent via theSOAPConnectionmethodcall.Due to the authentication and communication setup done when a
ProviderConnectionobject 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
ProviderConnectionobject cannot be used with a differentProviderConnectionobject.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description voidclose()Deprecated.Closes thisProviderConnectionobject, freeing its resources and making it immediately available for garbage collection.jakarta.xml.soap.MessageFactorycreateMessageFactory(java.lang.String profile)Deprecated.Creates aMessageFactoryobject that will produceSOAPMessageobjects for the given profile.ProviderMetaDatagetMetaData()Deprecated.Retrieves theProviderMetaDataobject that contains information about the messaging provider to which thisProviderConnectionobject is connected.voidsend(jakarta.xml.soap.SOAPMessage message)Deprecated.Sends the givenSOAPMessageobject and returns immediately after handing the message over to the messaging provider.
-
-
-
Method Detail
-
getMetaData
ProviderMetaData getMetaData() throws JAXMException
Deprecated.Retrieves theProviderMetaDataobject that contains information about the messaging provider to which thisProviderConnectionobject is connected.- Returns:
- the
ProviderMetaDataobject with information about the messaging provider - Throws:
JAXMException- if there is a problem getting theProviderMetaDataobject- See Also:
ProviderMetaData
-
close
void close() throws JAXMExceptionDeprecated.Closes thisProviderConnectionobject, 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
jakarta.xml.soap.MessageFactory createMessageFactory(java.lang.String profile) throws JAXMExceptionDeprecated.Creates aMessageFactoryobject that will produceSOAPMessageobjects for the given profile. TheMessageFactoryobject that is returned can create instances ofSOAPMessagesubclasses 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
MessageFactoryobject that will createSOAPMessageobjects 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
void send(jakarta.xml.soap.SOAPMessage message) throws JAXMException
Deprecated.Sends the givenSOAPMessageobject 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- theSOAPMessageobject that is to be sent asynchronously over thisProviderConnectionobject- Throws:
JAXMException- if a JAXM transmission error occurs
-
-