: Interface Connection

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.jms
Interface Connection

All Known Subinterfaces:: QueueConnection, TopicConnection, XAQueueConnection, XATopicConnection

public abstract 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:

It encapsulates an open connection with a JMS provider. It typically represents an open TCP/IP socket between a client and a provider service daemon.
Its creation is where client authenticating takes place.
It can specify a unique client identifier.
It provides ConnectionMetaData.
It supports an optional ExceptionListener.

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.

Version:: 1.0 - 3 August 1998
Author:: Mark Hapner, Rich Burridge
See Also:: 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.
`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.

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 Connections's client identifier using a provider-specific value.

The purpose of client identifier is to associate a session 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

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.

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

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. Restart begins with the oldest unacknowledged message. 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.

After stop is called there may still be some messages delivered.

Stopping a Session has no affect on its ability to send messages. Stopping a stopped session is ignored.

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.

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.