public interface Connection
extends java.lang.AutoCloseable
Connection object is a client's active connection to its JMS
provider. It typically allocates provider resources outside the Java virtual
machine (JVM).
Connections support concurrent use.
A connection serves several purposes:
ConnectionMetaData object.
ExceptionListener object.
Because the creation of a connection involves setting up authentication and communication, a connection is a relatively heavyweight object. Most clients will do all their messaging with a single connection. Other more advanced applications may use several connections. The JMS API 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 (that is, until all message consumers have been
created). At that point, the client calls
the connection's start method, 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 be started immediately, 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| Modifier and Type | Method and Description |
|---|---|
void |
close()
Closes the connection.
|
ConnectionConsumer |
createConnectionConsumer(Destination destination,
java.lang.String messageSelector,
ServerSessionPool sessionPool,
int maxMessages)
Creates a connection consumer for this connection (optional operation)
on the specific destination.
|
ConnectionConsumer |
createDurableConnectionConsumer(Topic topic,
java.lang.String subscriptionName,
java.lang.String messageSelector,
ServerSessionPool sessionPool,
int maxMessages)
Creates a connection consumer for this connection (optional operation)
on the specific topic using an unshared durable subscription with
the specified name.
|
Session |
createSession()
Creates a
Session object,
specifying no arguments. |
Session |
createSession(boolean transacted,
int acknowledgeMode)
Creates a
Session object,
specifying transacted and acknowledgeMode. |
Session |
createSession(int sessionMode)
Creates a
Session object, specifying sessionMode. |
ConnectionConsumer |
createSharedConnectionConsumer(Topic topic,
java.lang.String subscriptionName,
java.lang.String messageSelector,
ServerSessionPool sessionPool,
int maxMessages)
Creates a connection consumer for this connection (optional operation)
on the specific topic using a shared non-durable subscription with
the specified name.
|
ConnectionConsumer |
createSharedDurableConnectionConsumer(Topic topic,
java.lang.String subscriptionName,
java.lang.String messageSelector,
ServerSessionPool sessionPool,
int maxMessages)
Creates a connection consumer for this connection (optional operation)
on the specific topic using a shared durable subscription with
the specified name.
|
java.lang.String |
getClientID()
Gets the client identifier for this connection.
|
ExceptionListener |
getExceptionListener()
Gets the
ExceptionListener object for this connection. |
ConnectionMetaData |
getMetaData()
Gets the metadata for this connection.
|
void |
setClientID(java.lang.String clientID)
Sets the client identifier for this connection.
|
void |
setExceptionListener(ExceptionListener listener)
Sets an exception listener for this connection.
|
void |
start()
Starts (or restarts) a connection's delivery of incoming messages.
|
void |
stop()
Temporarily stops a connection's delivery of incoming messages.
|
Session createSession(boolean transacted, int acknowledgeMode) throws JMSException
Session object,
specifying transacted and acknowledgeMode.
This method has been superseded by the method createSession(int sessionMode)
which specifies the same information using a single argument,
and by the method createSession() which is for use in a Java EE JTA transaction.
Applications should consider using those methods instead of this one.
The effect of setting the transacted and acknowledgeMode
arguments depends on whether this method is called in a Java SE environment,
in the Java EE application client container, or in the Java EE web or EJB container.
If this method is called in the Java EE web or EJB container then the
effect of setting the transacted} and acknowledgeMode
arguments also depends on whether or not there is an active JTA transaction
in progress.
In a Java SE environment or in the Java EE application client container:
transacted is set to true then the session
will use a local transaction which may subsequently be committed or rolled back
by calling the session's commit or rollback methods.
The argument acknowledgeMode is ignored.
transacted is set to false then the session
will be non-transacted. In this case the argument acknowledgeMode
is used to specify how messages received by this session will be acknowledged.
The permitted values are
Session.CLIENT_ACKNOWLEDGE,
Session.AUTO_ACKNOWLEDGE and
Session.DUPS_OK_ACKNOWLEDGE.
For a definition of the meaning of these acknowledgement modes see the links below.
In a Java EE web or EJB container, when there is an active JTA transaction in progress:
transacted and acknowledgeMode are ignored.
The session will participate in the JTA transaction and will be committed or rolled back
when that transaction is committed or rolled back,
not by calling the session's commit or rollback methods.
Since both arguments are ignored, developers are recommended to use
createSession(), which has no arguments, instead of this method.
In the Java EE web or EJB container, when there is no active JTA transaction in progress:
transacted is ignored. The session will always be non-transacted,
using one of the two acknowledgement modes AUTO_ACKNOWLEDGE and DUPS_OK_ACKNOWLEDGE.
acknowledgeMode
is used to specify how messages received by this session will be acknowledged.
The only permitted values in this case are
Session.AUTO_ACKNOWLEDGE and
Session.DUPS_OK_ACKNOWLEDGE.
The value Session.CLIENT_ACKNOWLEDGE may not be used.
For a definition of the meaning of these acknowledgement modes see the links below.
Applications running in the Java EE web and EJB containers must not attempt
to create more than one active (not closed) Session object per connection.
If this method is called in a Java EE web or EJB container when an active
Session object already exists for this connection then a JMSException will be thrown.
transacted - indicates whether the session will use a local transaction.
If this method is called in the Java EE web or EJB container then this argument is ignored.acknowledgeMode - indicates how messages received by the session will be acknowledged.
Session.CLIENT_ACKNOWLEDGE,
Session.AUTO_ACKNOWLEDGE and
Session.DUPS_OK_ACKNOWLEDGE.
Session.AUTO_ACKNOWLEDGE and
Session.DUPS_OK_ACKNOWLEDGE.
In this case Session.CLIENT_ACKNOWLEDGE is not permitted.
JMSException - if the Connection object fails
to create a session due to
Session.AUTO_ACKNOWLEDGE,
Session.CLIENT_ACKNOWLEDGE,
Session.DUPS_OK_ACKNOWLEDGE,
createSession(int),
createSession()Session createSession(int sessionMode) throws JMSException
Session object, specifying sessionMode.
The effect of setting the sessionMode
argument depends on whether this method is called in a Java SE environment,
in the Java EE application client container, or in the Java EE web or EJB container.
If this method is called in the Java EE web or EJB container then the
effect of setting the sessionMode argument also depends on
whether or not there is an active JTA transaction in progress.
In a Java SE environment or in the Java EE application client container:
sessionMode is set to Session.SESSION_TRANSACTED then the session
will use a local transaction which may subsequently be committed or rolled back
by calling the session's commit or rollback methods.
sessionMode is set to any of
Session.CLIENT_ACKNOWLEDGE,
Session.AUTO_ACKNOWLEDGE or
Session.DUPS_OK_ACKNOWLEDGE.
then the session will be non-transacted and
messages received by this session will be acknowledged
according to the value of sessionMode.
For a definition of the meaning of these acknowledgement modes see the links below.
In a Java EE web or EJB container, when there is an active JTA transaction in progress:
sessionMode is ignored.
The session will participate in the JTA transaction and will be committed or rolled back
when that transaction is committed or rolled back,
not by calling the session's commit or rollback methods.
Since the argument is ignored, developers are recommended to use
createSession(), which has no arguments, instead of this method.
In the Java EE web or EJB container, when there is no active JTA transaction in progress:
acknowledgeMode must be set to either of
Session.AUTO_ACKNOWLEDGE or
Session.DUPS_OK_ACKNOWLEDGE.
The session will be non-transacted and messages received by this session will be acknowledged
automatically according to the value of acknowledgeMode.
For a definition of the meaning of these acknowledgement modes see the links below.
The values Session.SESSION_TRANSACTED and Session.CLIENT_ACKNOWLEDGE may not be used.
Applications running in the Java EE web and EJB containers must not attempt
to create more than one active (not closed) Session object per connection.
If this method is called in a Java EE web or EJB container when an active
Session object already exists for this connection then a JMSException will be thrown.
sessionMode - indicates which of four possible session modes will be used.
Session.SESSION_TRANSACTED,
Session.CLIENT_ACKNOWLEDGE,
Session.AUTO_ACKNOWLEDGE and
Session.DUPS_OK_ACKNOWLEDGE.
Session.AUTO_ACKNOWLEDGE and
Session.DUPS_OK_ACKNOWLEDGE.
In this case the values Session.TRANSACTED and Session.CLIENT_ACKNOWLEDGE are not permitted.
JMSException - if the Connection object fails
to create a session due to
Session.SESSION_TRANSACTED,
Session.AUTO_ACKNOWLEDGE,
Session.CLIENT_ACKNOWLEDGE,
Session.DUPS_OK_ACKNOWLEDGE,
createSession(boolean, int),
createSession()Session createSession() throws JMSException
Session object,
specifying no arguments.
The behaviour of the session that is created depends on whether this method is called in a Java SE environment, in the Java EE application client container, or in the Java EE web or EJB container. If this method is called in the Java EE web or EJB container then the behaviour of the session also depends on whether or not there is an active JTA transaction in progress.
In a Java SE environment or in the Java EE application client container:
Session.AUTO_ACKNOWLEDGE
For a definition of the meaning of this acknowledgement mode see the link below.
In a Java EE web or EJB container, when there is an active JTA transaction in progress:
commit or rollback methods.
In the Java EE web or EJB container, when there is no active JTA transaction in progress:
Session.AUTO_ACKNOWLEDGE
For a definition of the meaning of this acknowledgement mode see the link below.
Applications running in the Java EE web and EJB containers must not attempt
to create more than one active (not closed) Session object per connection.
If this method is called in a Java EE web or EJB container when an active
Session object already exists for this connection then a JMSException will be thrown.
JMSException - if the Connection object fails
to create a session due to
Session.AUTO_ACKNOWLEDGE,
createSession(boolean, int),
createSession(int)java.lang.String getClientID()
throws JMSException
This value is specific to the JMS provider. It is either preconfigured
by an administrator in a ConnectionFactory object
or assigned dynamically by the application by calling the
setClientID method.
JMSException - if the JMS provider fails to return
the client ID for this connection due
to some internal error.void setClientID(java.lang.String clientID)
throws JMSException
The preferred way to assign a JMS client's client identifier is for
it to be configured in a client-specific ConnectionFactory
object and transparently assigned to the Connection object
it creates.
Alternatively, a client can set a connection's client identifier
using a provider-specific value. The facility to set a connection's
client identifier explicitly 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 an
IllegalStateException. If a client sets the client identifier
explicitly, it must do so immediately after it creates 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 the 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 the JMS API is that required to support durable subscriptions.
If another connection with the same clientID is already running when
this method is called, the JMS provider should detect the duplicate ID and throw
an InvalidClientIDException.
This method must not be used in a Java EE web or EJB application.
Doing so may cause a JMSException to be thrown though this is not guaranteed.
clientID - the unique client identifierJMSException - if the JMS provider fails to set the client ID for the the connection
for one of the following reasons:
InvalidClientIDException - if the JMS client specifies an
invalid or duplicate client ID.IllegalStateException - if the JMS client attempts to set
a connection's client ID at the wrong time or
when it has been administratively configured.ConnectionMetaData getMetaData() throws JMSException
JMSException - if the JMS provider fails to
get the connection metadata for this connection.ConnectionMetaDataExceptionListener getExceptionListener() throws JMSException
ExceptionListener object for this connection.
Not every Connection has an ExceptionListener
associated with it.ExceptionListener for this connection, or null.
if no ExceptionListener is associated
with this connection.JMSException - if the JMS provider fails to
get the ExceptionListener for this
connection.setExceptionListener(javax.jms.ExceptionListener)void setExceptionListener(ExceptionListener listener) throws JMSException
If a JMS provider detects a serious problem with a connection, it
informs the connection's ExceptionListener, if one has been
registered. It does this by calling the listener's
onException method, passing it a JMSException
object describing the problem.
An exception listener allows a client to be notified of a problem asynchronously. 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 before it notifies the client of them.
This method must not be used in a Java EE web or EJB application.
Doing so may cause a JMSException to be thrown though this is not guaranteed.
listener - the exception listenerJMSException - if the JMS provider fails to set the exception listener
for one of the following reasons:
void start()
throws JMSException
start on a connection that has already been
started is ignored.JMSException - if the JMS provider fails to start
message delivery due to some internal error.stop()void stop() throws JMSException
start method. When
the connection is stopped, delivery to all the connection's message
consumers is inhibited: synchronous receives block, and messages are not
delivered to message listeners.
This call blocks until receives and/or message listeners in progress have completed.
Stopping a connection has no effect on its ability to send messages. A
call to stop on a connection that has already been stopped
is ignored.
A call to stop must not return until delivery of messages
has paused. This means that a client can rely on the fact that none of
its message listeners will be called and that all threads of control
waiting for receive calls 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 message listeners are running when stop is invoked, the
stop call must wait until all of them have returned before
it may return. While these message listeners are completing, they must
have the full services of the connection available to them.
A message listener must not attempt to stop its own connection as this would lead to deadlock. The JMS provider must detect this and throw a IllegalStateException.
For the avoidance of doubt, if an exception listener for this connection
is running when stop is invoked, there is no requirement for
the stop call to wait until the exception listener has
returned before it may return.
This method must not be used in a Java EE web or EJB application. Doing
so may cause a JMSException to be thrown though this is not
guaranteed.
IllegalStateException - this method has been called by a MessageListener
on its own ConnectionJMSException - if the JMS provider fails to stop message delivery for one
of the following reasons:
start()void close()
throws JMSException
Since a provider typically allocates significant resources outside the JVM on behalf of a connection, clients should close these resources 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.
Closing a connection causes all temporary destinations to be deleted.
When this method is invoked, it should not return until message
processing has been shut down in an orderly fashion. 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 with null, depending on whether there was a message available
at the time of the close. If one or more of the connection's sessions'
message listeners is processing a message at the time when connection
close is invoked, all the facilities of the connection and
its sessions must remain available to those listeners until they return
control to the JMS provider.
This method must not return until any incomplete asynchronous send operations for this Connection have been completed and any CompletionListener callbacks have returned. Incomplete sends should be allowed to complete normally unless an error occurs.
For the avoidance of doubt, if an exception listener for this connection
is running when close is invoked, there is no requirement for
the close call to wait until the exception listener has returned
before it may return.
Closing a connection causes any of its sessions' transactions
in progress to be rolled back. In the case where a session's
work is coordinated by an external transaction manager, a session's
commit and rollback methods are
not used and the result of a closed session's work is determined
later by the transaction manager.
Closing a connection does NOT force an
acknowledgment of client-acknowledged sessions.
A message listener must not attempt to close its own connection as this would lead to deadlock. The JMS provider must detect this and throw a IllegalStateException.
A CompletionListener callback method must not call close on its own Connection. Doing so will cause an IllegalStateException to be thrown.
Invoking the acknowledge method of a received message
from a closed connection's session must throw an
IllegalStateException. Closing a closed connection must
NOT throw an exception.
close in interface java.lang.AutoCloseableIllegalStateException - JMSException - if the JMS provider fails to close the
connection due to some internal error. For
example, a failure to release resources
or to close a socket connection can cause
this exception to be thrown.ConnectionConsumer createConnectionConsumer(Destination destination, java.lang.String messageSelector, ServerSessionPool sessionPool, int maxMessages) throws JMSException
This is an expert facility not used by ordinary JMS clients.
This method must not be used in a Java EE web or EJB application. Doing
so may cause a JMSException to be thrown though this is not
guaranteed.
destination - the destination to accessmessageSelector - only messages with properties matching the message selector
expression are delivered. A value of null or an empty string
indicates that there is no message selector for the message
consumer.sessionPool - the server session pool to associate with this connection
consumermaxMessages - the maximum number of messages that can be assigned to a
server session at one timeInvalidDestinationException - if an invalid destination is specified.InvalidSelectorException - if the message selector is invalid.JMSException - if the Connection object fails to create a
connection consumer for one of the following reasons:
sessionPool and
messageSelector or
ConnectionConsumerConnectionConsumer createSharedConnectionConsumer(Topic topic, java.lang.String subscriptionName, java.lang.String messageSelector, ServerSessionPool sessionPool, int maxMessages) throws JMSException
This is an expert facility not used by ordinary JMS clients.
This method must not be used in a Java EE web or EJB application. Doing
so may cause a JMSException to be thrown though this is not
guaranteed.
topic - the topic to accesssubscriptionName - the name used to identify the shared non-durable subscriptionmessageSelector - only messages with properties matching the message selector
expression are delivered. A value of null or an empty string
indicates that there is no message selector for the message
consumer.sessionPool - the server session pool to associate with this connection
consumermaxMessages - the maximum number of messages that can be assigned to a
server session at one timeIllegalStateException - if called on a QueueConnectionInvalidDestinationException - if an invalid destination is specified.InvalidSelectorException - if the message selector is invalid.JMSException - if the Connection object fails to create a
connection consumer for one of the following reasons:
sessionPool and
messageSelector or
ConnectionConsumerConnectionConsumer createDurableConnectionConsumer(Topic topic, java.lang.String subscriptionName, java.lang.String messageSelector, ServerSessionPool sessionPool, int maxMessages) throws JMSException
This is an expert facility not used by ordinary JMS clients.
This method must not be used in a Java EE web or EJB application. Doing
so may cause a JMSException to be thrown though this is not
guaranteed.
topic - topic to accesssubscriptionName - the name used to identify the unshared durable subscriptionmessageSelector - only messages with properties matching the message selector
expression are delivered. A value of null or an empty string
indicates that there is no message selector for the message
consumer.sessionPool - the server session pool to associate with this durable
connection consumermaxMessages - the maximum number of messages that can be assigned to a
server session at one timeIllegalStateException - if called on a QueueConnectionInvalidDestinationException - if an invalid destination is specified.InvalidSelectorException - if the message selector is invalid.JMSException - if the Connection object fails to create a
connection consumer for one of the following reasons:
sessionPool and messageSelector or
ConnectionConsumerConnectionConsumer createSharedDurableConnectionConsumer(Topic topic, java.lang.String subscriptionName, java.lang.String messageSelector, ServerSessionPool sessionPool, int maxMessages) throws JMSException
This is an expert facility not used by ordinary JMS clients.
This method must not be used in a Java EE web or EJB application. Doing
so may cause a JMSException to be thrown though this is not
guaranteed.
topic - topic to accesssubscriptionName - the name used to identify the shared durable subscriptionmessageSelector - only messages with properties matching the message selector
expression are delivered. A value of null or an empty string
indicates that there is no message selector for the message
consumer.sessionPool - the server session pool to associate with this durable
connection consumermaxMessages - the maximum number of messages that can be assigned to a
server session at one timeIllegalStateException - if called on a QueueConnectionInvalidDestinationException - if an invalid destination is specified.InvalidSelectorException - if the message selector is invalid.JMSException - if the Connection object fails to create a
connection consumer for one of the following reasons:
sessionPool and messageSelector or
ConnectionConsumer