org.ow2.joram.jakarta.jms

Class JMSContext

java.lang.Object

org.ow2.joram.jakarta.jms.JMSContext

All Implemented Interfaces:

jakarta.jms.JMSContext, AutoCloseable

public class JMSContext
extends Object
implements jakarta.jms.JMSContext

A JMSContext is the main interface in the simplified JMS API introduced for JMS 2.0. This combines in a single object the functionality of two separate objects from the JMS 1.1 API: a Connection and a Session.

When an application needs to send messages it use the createProducer method to create a JMSProducer which provides methods to configure and send messages. Messages may be sent either synchronously or asynchronously.

When an application needs to receive messages it uses one of several createConsumer or createDurableConsumer methods to create a JMSConsumer . A JMSConsumer provides methods to receive messages either synchronously or asynchronously.

In terms of the JMS 1.1 API a JMSContext should be thought of as representing both a Connection and a Session. Although the simplified API removes the need for applications to use those objects, the concepts of connection and session remain important. A connection represents a physical link to the JMS server and a session represents a single-threaded context for sending and receiving messages.

A JMSContext may be created by calling one of several createContext methods on a ConnectionFactory. A JMSContext that is created in this way is described as being application-managed. An application-managed JMSContext must be closed when no longer needed by calling its close method.

Applications running in the Java EE web and EJB containers may alternatively inject a JMSContext into their application using the @Inject annotation. A JMSContext that is created in this way is described as being container-managed. A container-managed JMSContext will be closed automatically by the container.

Applications running in the Java EE web and EJB containers are not permitted to create more than one active session on a connection so combining them in a single object takes advantage of this restriction to offer a simpler API.

However applications running in a Java SE environment or in the Java EE application client container are permitted to create multiple active sessions on the same connection. This allows the same physical connection to be used in multiple threads simultaneously. Such applications which require multiple sessions to be created on the same connection should use one of the createContext methods on the ConnectionFactory to create the first JMSContext and then use the createContext method on JMSContext to create additional JMSContext objects that use the same connection. All these JMSContext objects are application-managed and must be closed when no longer needed by calling their close method.

Since:

Joram 5.9

Field Summary

Fields

Modifier and Type	Field and Description
private boolean	closed Allows to prevent exception if the context is closed more than on time.
private ContextConnection	connection
static org.objectweb.util.monolog.api.Logger	logger
private Session	session

Fields inherited from interface jakarta.jms.JMSContext

AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE, SESSION_TRANSACTED

Constructor Summary

Constructors

Constructor and Description
JMSContext(jakarta.jms.Connection cnx) Creates a new Context using a newly created JMS connection.
JMSContext(jakarta.jms.Connection cnx, int sessionMode) Creates a new Context using a newly created JMS connection.
JMSContext(ContextConnection connection, int sessionMode) Creates a new Context sharing the connection of the calling context.

Method Summary

Modifier and Type	Method and Description
void	acknowledge()
void	close() API method.
void	commit()
jakarta.jms.QueueBrowser	createBrowser(jakarta.jms.Queue queue)
jakarta.jms.QueueBrowser	createBrowser(jakarta.jms.Queue queue, String messageSelector)
jakarta.jms.BytesMessage	createBytesMessage()
jakarta.jms.JMSConsumer	createConsumer(jakarta.jms.Destination destination)
jakarta.jms.JMSConsumer	createConsumer(jakarta.jms.Destination destination, String selector)
jakarta.jms.JMSConsumer	createConsumer(jakarta.jms.Destination destination, String selector, boolean noLocal)
jakarta.jms.JMSContext	createContext(int sessionMode) API method.
jakarta.jms.JMSConsumer	createDurableConsumer(jakarta.jms.Topic topic, String name)
JMSConsumer	createDurableConsumer(jakarta.jms.Topic topic, String name, String selector, boolean noLocal)
jakarta.jms.MapMessage	createMapMessage()
jakarta.jms.Message	createMessage()
jakarta.jms.ObjectMessage	createObjectMessage()
jakarta.jms.ObjectMessage	createObjectMessage(Serializable object)
JMSProducer	createProducer()
jakarta.jms.Queue	createQueue(String name)
jakarta.jms.JMSConsumer	createSharedConsumer(jakarta.jms.Topic topic, String sharedSubscriptionName)
jakarta.jms.JMSConsumer	createSharedConsumer(jakarta.jms.Topic topic, String sharedSubscriptionName, String messageSelector)
jakarta.jms.JMSConsumer	createSharedDurableConsumer(jakarta.jms.Topic topic, String name)
jakarta.jms.JMSConsumer	createSharedDurableConsumer(jakarta.jms.Topic topic, String name, String messageSelector)
jakarta.jms.StreamMessage	createStreamMessage()
jakarta.jms.TemporaryQueue	createTemporaryQueue()
jakarta.jms.TemporaryTopic	createTemporaryTopic()
jakarta.jms.TextMessage	createTextMessage()
jakarta.jms.TextMessage	createTextMessage(String text)
jakarta.jms.Topic	createTopic(String name)
boolean	getAutoStart()
String	getClientID()
private Session	getCopyOfSession()
jakarta.jms.ExceptionListener	getExceptionListener()
jakarta.jms.ConnectionMetaData	getMetaData()
(package private) Session	getSession()
int	getSessionMode() JMS 2.0 API method.
boolean	getTransacted()
void	recover()
void	rollback()
void	setAutoStart(boolean autoStart)
void	setClientID(String clientID)
void	setExceptionListener(jakarta.jms.ExceptionListener listener)
void	start()
void	stop() Temporarily stops the delivery of incoming messages by the JMSContext's connection.
void	unsubscribe(String name)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

logger

public static org.objectweb.util.monolog.api.Logger logger

closed

private boolean closed

Allows to prevent exception if the context is closed more than on time.

connection

private ContextConnection connection

session

private Session session

Constructor Detail

JMSContext

public JMSContext(ContextConnection connection,
                  int sessionMode)

Creates a new Context sharing the connection of the calling context.

Parameters:

connection - the connection of the calling context.

sessionMode - indicates which of four possible session modes will be used.

JMSContext

public JMSContext(jakarta.jms.Connection cnx)

Creates a new Context using a newly created JMS connection.

Parameters:

cnx - the created JMS connection.

JMSContext

public JMSContext(jakarta.jms.Connection cnx,
                  int sessionMode)

Creates a new Context using a newly created JMS connection.

Parameters:

cnx - the created JMS connection.

sessionMode - indicates which of four possible session modes will be used.

Method Detail

createContext

public jakarta.jms.JMSContext createContext(int sessionMode)

API method. Creates a new JMSContext with the specified session mode using the same connection as this JMSContext and creating a new session.

This method does not start the connection. If the connection has not already been started then it will be automatically started when a JMSConsumer is created on any of the JMSContext objects for that connection.

• If sessionMode is set to JMSContext.SESSION_TRANSACTED then the session will use a local transaction which may subsequently be committed or rolled back by calling the JMSContext's commit or rollback methods.
• If sessionMode is set to any of JMSContext.CLIENT_ACKNOWLEDGE, JMSContext.AUTO_ACKNOWLEDGE or JMSContext.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.

This method must not be used by applications running in the Java EE web or EJB containers because doing so would violate the restriction that such an application 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 then a JMSRuntimeException will be thrown.

Specified by:

createContext in interface jakarta.jms.JMSContext

Parameters:

sessionMode - indicates which of four possible session modes will be used. The permitted values are JMSContext.SESSION_TRANSACTED, JMSContext.CLIENT_ACKNOWLEDGE, JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE.

Returns:

a newly created JMSContext

Throws:

jakarta.jms.JMSRuntimeException - if the JMS provider fails to create the JMSContext due to

• some internal error or
• because this method is being called in a Java EE web or EJB application.

Since:

JMS 2.0

See Also:

JMSContext.SESSION_TRANSACTED, JMSContext.CLIENT_ACKNOWLEDGE, JMSContext.AUTO_ACKNOWLEDGE, JMSContext.DUPS_OK_ACKNOWLEDGE, ConnectionFactory.createContext(), ConnectionFactory.createContext(int), ConnectionFactory.createContext(java.lang.String, java.lang.String), ConnectionFactory.createContext(java.lang.String, java.lang.String, int), JMSContext.createContext(int)

close

public void close()

API method. Closes the JMSContext

This closes the underlying session and any underlying producers and consumers. If there are no other active (not closed) JMSContext objects using the underlying connection then this method also closes the underlying connection.

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.

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 JMSContext 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 the JMSContext's 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.

Invoking the acknowledge method of a received message from a closed connection's session must throw an IllegalStateRuntimeException. Closing a closed connection must NOT throw an exception.

A MessageListener must not attempt to close its own JMSContext as this would lead to deadlock. The JMS provider must detect this and throw a IllegalStateRuntimeException.

A CompletionListener callback method must not call close on its own JMSContext. Doing so will cause an IllegalStateRuntimeException to be thrown.

This method must not be used if the JMSContext is container-managed (injected). Doing so will cause a IllegalStateRuntimeException to be thrown.

Specified by:

close in interface jakarta.jms.JMSContext

Specified by:

close in interface AutoCloseable

Throws:

jakarta.jms.IllegalStateRuntimeException -

• if this method has been called by a MessageListener on its own JMSContext
• if this method has been called by a CompletionListener callback method on its own JMSContext
• if the JMSContext is container-managed (injected)

jakarta.jms.JMSRuntimeException - if the JMS provider fails to close the JMSContext 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.

acknowledge

public void acknowledge()

Specified by:

acknowledge in interface jakarta.jms.JMSContext

commit

public void commit()

Specified by:

commit in interface jakarta.jms.JMSContext

recover

public void recover()

Specified by:

recover in interface jakarta.jms.JMSContext

rollback

public void rollback()

Specified by:

rollback in interface jakarta.jms.JMSContext

createMessage

public jakarta.jms.Message createMessage()

Specified by:

createMessage in interface jakarta.jms.JMSContext

createBytesMessage

public jakarta.jms.BytesMessage createBytesMessage()

Specified by:

createBytesMessage in interface jakarta.jms.JMSContext

createMapMessage

public jakarta.jms.MapMessage createMapMessage()

Specified by:

createMapMessage in interface jakarta.jms.JMSContext

createObjectMessage

public jakarta.jms.ObjectMessage createObjectMessage()

Specified by:

createObjectMessage in interface jakarta.jms.JMSContext

createObjectMessage

public jakarta.jms.ObjectMessage createObjectMessage(Serializable object)

Specified by:

createObjectMessage in interface jakarta.jms.JMSContext

createTextMessage

public jakarta.jms.TextMessage createTextMessage()

Specified by:

createTextMessage in interface jakarta.jms.JMSContext

createTextMessage

public jakarta.jms.TextMessage createTextMessage(String text)

Specified by:

createTextMessage in interface jakarta.jms.JMSContext

createStreamMessage

public jakarta.jms.StreamMessage createStreamMessage()

Specified by:

createStreamMessage in interface jakarta.jms.JMSContext

createTemporaryQueue

public jakarta.jms.TemporaryQueue createTemporaryQueue()

Specified by:

createTemporaryQueue in interface jakarta.jms.JMSContext

createTemporaryTopic

public jakarta.jms.TemporaryTopic createTemporaryTopic()

Specified by:

createTemporaryTopic in interface jakarta.jms.JMSContext

createQueue

public jakarta.jms.Queue createQueue(String name)

Specified by:

createQueue in interface jakarta.jms.JMSContext

createTopic

public jakarta.jms.Topic createTopic(String name)

Specified by:

createTopic in interface jakarta.jms.JMSContext

getAutoStart

public boolean getAutoStart()

Specified by:

getAutoStart in interface jakarta.jms.JMSContext

setAutoStart

public void setAutoStart(boolean autoStart)

Specified by:

setAutoStart in interface jakarta.jms.JMSContext

createConsumer

public jakarta.jms.JMSConsumer createConsumer(jakarta.jms.Destination destination)

Specified by:

createConsumer in interface jakarta.jms.JMSContext

createConsumer

public jakarta.jms.JMSConsumer createConsumer(jakarta.jms.Destination destination,
                                              String selector)

Specified by:

createConsumer in interface jakarta.jms.JMSContext

createConsumer

public jakarta.jms.JMSConsumer createConsumer(jakarta.jms.Destination destination,
                                              String selector,
                                              boolean noLocal)

Specified by:

createConsumer in interface jakarta.jms.JMSContext

createBrowser

public jakarta.jms.QueueBrowser createBrowser(jakarta.jms.Queue queue)

Specified by:

createBrowser in interface jakarta.jms.JMSContext

createBrowser

public jakarta.jms.QueueBrowser createBrowser(jakarta.jms.Queue queue,
                                              String messageSelector)

Specified by:

createBrowser in interface jakarta.jms.JMSContext

createDurableConsumer

public jakarta.jms.JMSConsumer createDurableConsumer(jakarta.jms.Topic topic,
                                                     String name)

Specified by:

createDurableConsumer in interface jakarta.jms.JMSContext

createDurableConsumer

public JMSConsumer createDurableConsumer(jakarta.jms.Topic topic,
                                         String name,
                                         String selector,
                                         boolean noLocal)

Specified by:

createDurableConsumer in interface jakarta.jms.JMSContext

createProducer

public JMSProducer createProducer()

Specified by:

createProducer in interface jakarta.jms.JMSContext

createSharedConsumer

public jakarta.jms.JMSConsumer createSharedConsumer(jakarta.jms.Topic topic,
                                                    String sharedSubscriptionName)

Specified by:

createSharedConsumer in interface jakarta.jms.JMSContext

createSharedConsumer

public jakarta.jms.JMSConsumer createSharedConsumer(jakarta.jms.Topic topic,
                                                    String sharedSubscriptionName,
                                                    String messageSelector)

Specified by:

createSharedConsumer in interface jakarta.jms.JMSContext

createSharedDurableConsumer

public jakarta.jms.JMSConsumer createSharedDurableConsumer(jakarta.jms.Topic topic,
                                                           String name)

Specified by:

createSharedDurableConsumer in interface jakarta.jms.JMSContext

createSharedDurableConsumer

public jakarta.jms.JMSConsumer createSharedDurableConsumer(jakarta.jms.Topic topic,
                                                           String name,
                                                           String messageSelector)

Specified by:

createSharedDurableConsumer in interface jakarta.jms.JMSContext

getCopyOfSession

private Session getCopyOfSession()

getSessionMode

public int getSessionMode()

JMS 2.0 API method. Returns the session mode of the JMSContext's session. This can be set at the time that the JMSContext is created. Possible values are JMSContext.SESSION_TRANSACTED, JMSContext.AUTO_ACKNOWLEDGE, JMSContext.CLIENT_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE

If a session mode was not specified when the JMSContext was created a value of JMSContext.AUTO_ACKNOWLEDGE will be returned.

Specified by:

getSessionMode in interface jakarta.jms.JMSContext

Returns:

the session mode of the JMSContext's session

Throws:

jakarta.jms.JMSRuntimeException - if the JMS provider fails to return the acknowledgment mode due to some internal error.

Since:

JMS 2.0

See Also:

Connection.createSession(boolean, int)

getTransacted

public boolean getTransacted()

Specified by:

getTransacted in interface jakarta.jms.JMSContext

getMetaData

public jakarta.jms.ConnectionMetaData getMetaData()

Specified by:

getMetaData in interface jakarta.jms.JMSContext

getClientID

public String getClientID()

Specified by:

getClientID in interface jakarta.jms.JMSContext

setClientID

public void setClientID(String clientID)

Specified by:

setClientID in interface jakarta.jms.JMSContext

getExceptionListener

public jakarta.jms.ExceptionListener getExceptionListener()

Specified by:

getExceptionListener in interface jakarta.jms.JMSContext

setExceptionListener

public void setExceptionListener(jakarta.jms.ExceptionListener listener)

Specified by:

setExceptionListener in interface jakarta.jms.JMSContext

start

public void start()

Specified by:

start in interface jakarta.jms.JMSContext

stop

public void stop()

Temporarily stops the delivery of incoming messages by the JMSContext's connection. Delivery can be restarted using the 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 JMSContext as this would lead to deadlock. The JMS provider must detect this and throw a IllegalStateRuntimeException

For the avoidance of doubt, if an exception listener for the JMSContext's 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 JMSRuntimeException to be thrown though this is not guaranteed.

This method must not be used if the JMSContext is container-managed (injected). Doing so will cause a IllegalStateRuntimeException to be thrown.

Specified by:

stop in interface jakarta.jms.JMSContext

Throws:

jakarta.jms.IllegalStateRuntimeException -

• if this method has been called by a MessageListener on its own JMSContext
• if the JMSContext is container-managed (injected).

jakarta.jms.JMSRuntimeException - if the JMS provider fails to stop message delivery for one of the following reasons:

• an internal error has occurred or
• this method has been called in a Java EE web or EJB application (though it is not guaranteed that an exception is thrown in this case)

See Also:

JMSContext.start()

unsubscribe

public void unsubscribe(String name)

Specified by:

unsubscribe in interface jakarta.jms.JMSContext

getSession

Session getSession()