|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
A JMS Connection is a client's active connection to its JMS provider. It will typically allocate provider resources outside the Java virtual machine.
Connections support concurrent use.
A Connection serves several purposes:
Due to the authentication and communication setup done when a Connection is created, a Connection is a relatively heavy-weight JMS object. Most clients will do all their messaging with a single Connection. Other more advanced applications may use several Connections. JMS does not architect a reason for using multiple connections; however, there may be operational reasons for doing so.
A JMS client typically creates a Connection; one or more Sessions; and a number of message producers and consumers. When a Connection is created it is in stopped mode. That means that no messages are being delivered.
It is typical to leave the Connection in stopped mode until setup is complete. At that point the Connection's start() method is called and messages begin arriving at the Connection's consumers. This setup convention minimizes any client confusion that may result from asynchronous message delivery while the client is still in the process of setting itself up.
A Connection can immediately be started and the setup can be done afterwards. Clients that do this must be prepared to handle asynchronous message delivery while they are still in the process of setting up.
A message producer can send messages while a Connection is stopped.
ConnectionFactory
,
QueueConnection
,
TopicConnection
Method Summary | |
void |
close()
Since a provider typically allocates significant resources outside the JVM on behalf of a Connection, clients should close them when they are not needed. |
java.lang.String |
getClientID()
Get the client identifier for this connection. |
ExceptionListener |
getExceptionListener()
Get the ExceptionListener for this Connection. |
ConnectionMetaData |
getMetaData()
Get the meta data for this connection. |
void |
setClientID(java.lang.String clientID)
Set the client identifier for this connection. |
void |
setExceptionListener(ExceptionListener listener)
Set an exception listener for this connection. |
void |
start()
Start (or restart) a Connection's delivery of incoming messages. |
void |
stop()
Used to temporarily stop a Connection's delivery of incoming messages. |
Method Detail |
public java.lang.String getClientID() throws JMSException
setClientID
method.public void setClientID(java.lang.String clientID) throws JMSException
The preferred way to assign a Client's client identifier is for it to be configured in a client-specific ConnectionFactory and transparently assigned to the Connection it creates.
Alternatively, a client can set a connection's client identifier using a provider-specific value. The facility to explicitly set a connection's client identifier is not a mechanism for overriding the identifier that has been administratively configured. It is provided for the case where no administratively specified identifier exists. If one does exist, an attempt to change it by setting it must throw a IllegalStateException. If a client explicitly does the set it must do this immediately after creating the connection and before any other action on the connection is taken. After this point, setting the client identifier is a programming error that should throw an IllegalStateException.
The purpose of client identifier is to associate a connection and its objects with a state maintained on behalf of the client by a provider. The only such state identified by JMS is that required to support durable subscriptions
If another connection with clientID
is already running when
this method is called, the JMS Provider should detect the duplicate id and throw
InvalidClientIDException.
clientID
- the unique client identifierpublic ConnectionMetaData getMetaData() throws JMSException
ConnectionMetaData
public ExceptionListener getExceptionListener() throws JMSException
public void setExceptionListener(ExceptionListener listener) throws JMSException
If a JMS provider detects a serious problem with a connection it will inform the connection's ExceptionListener if one has been registered. It does this by calling the listener's onException() method passing it a JMSException describing the problem.
This allows a client to be asynchronously notified of a problem. Some connections only consume messages so they would have no other way to learn their connection has failed.
A Connection serializes execution of its ExceptionListener.
A JMS provider should attempt to resolve connection problems itself prior to notifying the client of them.
handler
- the exception listener.public void start() throws JMSException
stop()
public void stop() throws JMSException
start
method. When stopped,
delivery to all the Connection's message consumers is inhibited:
synchronous receive's block and messages are not delivered to message
listeners.
This call blocks until receives and/or message listeners in progress have completed.
Stopping a Session has no affect on its ability to send messages. Stopping a stopped session is ignored.
A stop method call must not return until delivery of messages has paused. This means a client can rely on the fact that none of its message listeners will be called and all threads of control waiting for receive to return will not return with a message until the connection is restarted. The receive timers for a stopped connection continue to advance so receives may time out while the connection is stopped.
If MessageListeners are running when stop is invoked, stop must wait until all of them have returned before it may return. While these MessageListeners are completing, they must have full services of the connection available to them.
start()
public void close() throws JMSException
There is no need to close the sessions, producers, and consumers of a closed connection.
When this method is invoked it should not return until message processing has been orderly shut down. This means that all message listeners that may have been running have returned and that all pending receives have returned. A close terminates all pending message receives on the connection's sessions' consumers. The receives may return with a message or null depending on whether there was a message or not available at the time of the close. If one or more of the connection's sessions' message listeners is processing a message at the point connection close is invoked, all the facilities of the connection and it's sessions must remain available to those listeners until they return control to the JMS provider.
Closing a connection causes any of its sessions' in-process transactions to be rolled back. In the case where a session's work is coordinated by an external transaction manager, when using XASession, a session's commit and rollback methods are not used and the result of a closed session's work is determined later by a transaction manager. Closing a connection does NOT force an acknowledge of client acknowledged sessions.
Invoking the session acknowledge method on a closed connection's session must throw a JMSException. Closing a closed connection must NOT throw an exception.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |