Package org.objectweb.joram.client.jms

Class JMSContext

  • All Implemented Interfaces:
    AutoCloseable, JMSContext
    public class JMSContext
extends Object
implements 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 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.

    • 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​(Connection cnx)
        Creates a new Context using a newly created JMS connection.
        Parameters:
        cnx - the created JMS connection.

      • JMSContext

        public JMSContext​(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 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 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:
        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 AutoCloseable
        Specified by:
        close in interface JMSContext
        Throws:
        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)
        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.

      • setAutoStart

        public void setAutoStart​(boolean autoStart)
        Specified by:
        setAutoStart in interface 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 JMSContext
        Returns:
        the session mode of the JMSContext's session
        Throws:
        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)

      • start

        public void start()
        Specified by:
        start in interface 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 JMSContext
        Throws:
        IllegalStateRuntimeException -
        • if this method has been called by a MessageListener on its own JMSContext
        • if the JMSContext is container-managed (injected).
        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()