Managing Your Applications 6-11
Once started, you can stop a connection using the stop method. This method performs the following steps:
■
Pauses the delivery of all messages. No applications waiting to receive messages will return until the connection is restarted or the time-to-live value associated
with the message is reached.
■
Waits until all message listeners that are currently processing messages have completed.
Typically, a JMS Provider allocates a significant amount of resources when it creates a connection. When a connection is no longer being used, you should close it to free up
resources. A connection can be closed using the following method:
public void close throws JMSException
This method performs the following steps to execute an orderly shutdown:
■
Terminates the receipt of all pending messages. Applications may return a message or null if a message was not available at the time of the close.
■
Waits until all message listeners that are currently processing messages have completed.
■
Rolls back in-process transactions on its transacted sessions unless such transactions are part of an external JTA user transaction. For more information
about JTA user transactions, see Section 12.3, Using JTA User Transactions.
■
Does not force an acknowledge of client-acknowledged sessions. By not forcing an acknowledge, no messages are lost for queues and durable subscriptions that
require reliable processing.
When you close a connection, all associated objects are also closed. You can continue to use the message objects created or received via the connection, except the received
messages acknowledge method. Closing a closed connection has no effect.
6.4 Managing Sessions
The following sections describe how to manage sessions, including:
■
Section 6.4.1, Defining a Session Exception Listener
■
Section 6.4.2, Closing a Session
6.4.1 Defining a Session Exception Listener
An exception listener asynchronously notifies a client in the event a problem occurs with a session. This is particularly useful for a session waiting to consume messages
that might not be notified otherwise.
Note: Attempting to acknowledge a received message from a closed
connections session throws an IllegalStateException.
Note:
The purpose of an exception listener is not to monitor all exceptions thrown by a session, only to deliver those exceptions that
would otherwise be undelivered.
6-12 Programming JMS for Oracle WebLogic Server
You can define an exception listener for a session using the following WLSession method:
public void setExceptionListener ExceptionListener listener
throws JMSException
You must specify an ExceptionListener object for the session. The JMS Provider notifies an exception listener, if one has been defined, when it
encounters a problem with a session using the following ExceptionListener method:
public void onException JMSException exception
The JMS Provider specifies the exception encountered that describes the problem when calling the method.
You can access the exception listener for a session using the following WLSession method:
public ExceptionListener getExceptionListener throws JMSException
6.4.2 Closing a Session
As with connections, a JMS Provider allocates a significant amount of resources when it creates a session. When a session is no longer being used, it is recommended that it
be closed to free up resources. A session can be closed using the following Session method:
public void close throws JMSException
This method performs the following steps to execute an orderly shutdown:
■
Terminates the receipt of all pending messages. Applications may return a message or null if a message was not available at the time of the close.
■
Waits until all message listeners that are currently processing messages have completed.
■
Rolls back in-process transactions unless such transactions are part of external JTA user transaction. For more information about JTA user transactions, see
Section 12.3, Using JTA User Transactions.
Note: Because there can only be one thread per session, an exception
listener and message listener used for asynchronous message delivery cannot execute simultaneously. Consequently, if a message
listener is executing at the time a problem occurs, execution of the exception listener is blocked until the message listener completes its
execution. For more information about message listeners, see
Section 5.4.1, Receiving Messages Asynchronously.
Note:
The close method is the only Session method that can be invoked from a thread that is separate from the session thread.
Managing Your Applications 6-13
■
Does not force an acknowledge of client acknowledged sessions, ensuring that no messages are lost for queues and durable subscriptions that require reliable
processing.
When you close a session, all associated producers and consumers are also closed.
6.5 Managing Destinations
