javax.jms
Interface Connection

All Known Subinterfaces:
QueueConnection, TopicConnection, XAQueueConnection, XATopicConnection

public interface Connection

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.

See Also:
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

getClientID

public java.lang.String getClientID()
                             throws JMSException
Get the client identifier for this connection. This value is JMS Provider specific. Either pre-configured by an administrator in a ConnectionFactory or assigned dynamically by the application by calling setClientID method.
Returns:
the unique client identifier.
Throws:
JMSException - if JMS implementation fails to return the client ID for this Connection due to some internal error.

setClientID

public void setClientID(java.lang.String clientID)
                 throws JMSException
Set the client identifier for this connection.

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.

Parameters:
clientID - the unique client identifier
Throws:
JMSException - general exception if JMS implementation fails to set the client ID for this Connection due to some internal error.
InvalidClientIDException - if JMS client specifies an invalid or duplicate client id.
IllegalStateException - if attempting to set a connection's client identifier at the wrong time or when it has been administratively configured.

getMetaData

public ConnectionMetaData getMetaData()
                               throws JMSException
Get the meta data for this connection.
Returns:
the connection meta data.
Throws:
JMSException - general exception if JMS implementation fails to get the Connection meta-data for this Connection.
See Also:
ConnectionMetaData

getExceptionListener

public ExceptionListener getExceptionListener()
                                       throws JMSException
Get the ExceptionListener for this Connection.
Returns:
the ExceptionListener for this Connection.
Throws:
JMSException - general exception if JMS implementation fails to get the Exception listener for this Connection.

setExceptionListener

public void setExceptionListener(ExceptionListener listener)
                          throws JMSException
Set an exception listener for this connection.

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.

Parameters:
handler - the exception listener.
Throws:
JMSException - general exception if JMS implementation fails to set the Exception listener for this Connection.

start

public void start()
           throws JMSException
Start (or restart) a Connection's delivery of incoming messages. Starting a started session is ignored.
Throws:
JMSException - if JMS implementation fails to start the message delivery due to some internal error.
See Also:
stop()

stop

public void stop()
          throws JMSException
Used to temporarily stop a Connection's delivery of incoming messages. It can be restarted using its 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.

Throws:
JMSException - if JMS implementation fails to stop the message delivery due to some internal error.
See Also:
start()

close

public void close()
           throws JMSException
Since a provider typically allocates significant resources outside the JVM on behalf of a Connection, clients should close them when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough.

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.

Throws:
JMSException - if JMS implementation fails to close the connection due to internal error. For example, a failure to release resources or to close socket connection can lead to throwing of this exception.