EE4J 10.0.0 · jakarta.jms.JMSContext

A JMSContext is the main interface in the simplified Jakarta Messaging API introduced for Jakarta Messaging 2.0. This combines in a single object the functionality of two separate objects from the Java Message Service 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 Java Message Service 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 Jakarta Messaging 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 Jakarta 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 Jakarta 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 Jakarta 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.

Modifier and Type	Field and Description
public static final int	AUTO_ACKNOWLEDGE With this session mode, the JMSContext's session automatically acknowledges a client's receipt of a message either when the session has successfully returned from a call to `receive` or when the message listener the session has called to process the message successfully returns.
public static final int	CLIENT_ACKNOWLEDGE With this session mode, the client acknowledges a consumed message by calling the message's `acknowledge` method.
public static final int	DUPS_OK_ACKNOWLEDGE This session mode instructs the JMSContext's session to lazily acknowledge the delivery of messages.
public static final int	SESSION_TRANSACTED This session mode instructs the JMSContext's session to deliver and consume messages in a local transaction which will be subsequently committed by calling `commit` or rolled back by calling `rollback`.

Method Summary

Modifier and Type	Method and Description
public void	acknowledge() Acknowledges all messages consumed by the JMSContext's session.
public void	close() Redeclares java.lang.AutoCloseable.close. Closes the JMSContext This closes the underlying session and any underlying producers and consumers.
public void	commit() Commits all messages done in this transaction and releases any locks currently held.
public QueueBrowser	Returns: The created `QueueBrowser` object. createBrowser(Queue the `queue` to access queue) Creates a `QueueBrowser` object to peek at the messages on the specified queue.
public QueueBrowser	Returns: The created `QueueBrowser` object. createBrowser(Queue the `queue` to access queue, String 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. messageSelector) Creates a `QueueBrowser` object to peek at the messages on the specified queue using a message selector.
public BytesMessage	Returns: The created `BytesMessage` object createBytesMessage() Creates a `BytesMessage` object.
public JMSConsumer	Returns: The created `JMSConsumer` object. createConsumer(Destination the `Destination` to access. destination) Creates a `JMSConsumer` for the specified destination.
public JMSConsumer	Returns: The created `JMSConsumer` object. createConsumer(Destination the `Destination` to access destination, String 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 `JMSConsumer`. messageSelector) Creates a `JMSConsumer` for the specified destination, using a message selector.
public JMSConsumer	Returns: The created `JMSConsumer` object. createConsumer(Destination the `Destination` to access destination, String 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 `JMSConsumer`. messageSelector, boolean if true, and the destination is a topic, then the `JMSConsumer` will not receive messages published to the topic by its own connection noLocal) Creates a `JMSConsumer` for the specified destination, specifying a message selector and the `noLocal` parameter.
public JMSContext	Returns: a newly created JMSContext createContext(int 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`. sessionMode) Creates a new `JMSContext` with the specified session mode using the same connection as this `JMSContext` and creating a new session.
public JMSConsumer	Returns: The created `JMSConsumer` object. createDurableConsumer(Topic the non-temporary `Topic` to subscribe to topic, String the name used to identify this subscription name) Creates an unshared durable subscription on the specified topic (if one does not already exist) and creates a consumer on that durable subscription.
public JMSConsumer	Returns: The created `JMSConsumer` object. createDurableConsumer(Topic the non-temporary `Topic` to subscribe to topic, String the name used to identify this subscription name, String only messages with properties matching the message selector expression are added to the durable subscription. A value of null or an empty string indicates that there is no message selector for the durable subscription. messageSelector, boolean if true then any messages published to the topic using this session's connection, or any other connection with the same client identifier, will not be added to the durable subscription. noLocal) Creates an unshared durable subscription on the specified topic (if one does not already exist), specifying a message selector and the `noLocal` parameter, and creates a consumer on that durable subscription.
public MapMessage	Returns: The created `MapMessage` object. createMapMessage() Creates a `MapMessage` object.
public Message	Returns: The created `Message` object. createMessage() Creates a `Message` object.
public ObjectMessage	Returns: The created `ObjectMessage` object. createObjectMessage() Creates an `ObjectMessage` object.
public ObjectMessage	Returns: The created `ObjectMessage` object. createObjectMessage(Serializable the object to use to initialize this message object) Creates an initialized `ObjectMessage` object.
public JMSProducer	Returns: A new `JMSProducer` object createProducer() Creates a new `JMSProducer` object which can be used to configure and send messages
public Queue	Returns: a Queue object which encapsulates the specified name createQueue(String A provider-specific queue name queueName) Creates a `Queue` object which encapsulates a specified provider-specific queue name.
public JMSConsumer	Returns: The created `JMSConsumer` object. createSharedConsumer(Topic the `Topic` to subscribe to topic, String the name used to identify the shared non-durable subscription sharedSubscriptionName) Creates a shared non-durable subscription with the specified name on the specified topic (if one does not already exist) and creates a consumer on that subscription.
public JMSConsumer	Returns: The created `JMSConsumer` object. createSharedConsumer(Topic the `Topic` to subscribe to topic, String the name used to identify the shared non-durable subscription sharedSubscriptionName, String only messages with properties matching the message selector expression are added to the shared non-durable subscription. A value of null or an empty string indicates that there is no message selector for the shared non-durable subscription. messageSelector) Creates a shared non-durable subscription with the specified name on the specified topic (if one does not already exist) specifying a message selector, and creates a consumer on that subscription.
public JMSConsumer	Returns: The created `JMSConsumer` object. createSharedDurableConsumer(Topic the non-temporary `Topic` to subscribe to topic, String the name used to identify this subscription name) Creates a shared durable subscription on the specified topic (if one does not already exist), specifying a message selector, and creates a consumer on that durable subscription.
public JMSConsumer	Returns: The created `JMSConsumer` object. createSharedDurableConsumer(Topic the non-temporary `Topic` to subscribe to topic, String the name used to identify this subscription name, String only messages with properties matching the message selector expression are added to the durable subscription. A value of null or an empty string indicates that there is no message selector for the durable subscription. messageSelector) Creates a shared durable subscription on the specified topic (if one does not already exist), specifying a message selector, and creates a consumer on that durable subscription.
public StreamMessage	Returns: The created `StreamMessage` object. createStreamMessage() Creates a `StreamMessage` object.
public TemporaryQueue	Returns: a temporary queue identity createTemporaryQueue() Creates a `TemporaryQueue` object.
public TemporaryTopic	Returns: a temporary topic identity createTemporaryTopic() Creates a `TemporaryTopic` object.
public TextMessage	Returns: The created `TextMessage` object. createTextMessage() Creates a `TextMessage` object.
public TextMessage	Returns: The created `TextMessage` object. createTextMessage(String the string used to initialize this message text) Creates an initialized `TextMessage` object.
public Topic	Returns: a Topic object which encapsulates the specified name createTopic(String A provider-specific topic name topicName) Creates a `Topic` object which encapsulates a specified provider-specific topic name.
public boolean	Returns: whether the underlying connection used by this `JMSContext` will be started automatically when a consumer is created. getAutoStart() Returns whether the underlying connection used by this `JMSContext` will be started automatically when a consumer is created.
public String	Returns: the unique client identifier getClientID() Gets the client identifier for the JMSContext's connection.
public ExceptionListener	Returns: the `ExceptionListener` for the JMSContext's connection, or null if no `ExceptionListener` is associated with that connection. getExceptionListener() Gets the `ExceptionListener` object for the JMSContext's connection.
public ConnectionMetaData	Returns: the connection metadata getMetaData() Gets the connection metadata for the JMSContext's connection.
public int	Returns: the session mode of the JMSContext's session getSessionMode() Returns the session mode of the JMSContext's session.
public boolean	Returns: true if the session is in transacted mode getTransacted() Indicates whether the JMSContext's session is in transacted mode.
public void	recover() Stops message delivery in the JMSContext's session, and restarts message delivery with the oldest unacknowledged message.
public void	rollback() Rolls back any messages done in this transaction and releases any locks currently held.
public void	setAutoStart(boolean Whether the underlying connection used by this `JMSContext` will be automatically started when a consumer is created. autoStart) Specifies whether the underlying connection used by this `JMSContext` will be started automatically when a consumer is created.
public void	setClientID(String the unique client identifier clientID) Sets the client identifier for the JMSContext's connection.
public void	setExceptionListener(ExceptionListener the exception listener listener) Sets an exception listener for the JMSContext's connection.
public void	start() Starts (or restarts) delivery of incoming messages by the JMSContext's connection.
public void	stop() Temporarily stops the delivery of incoming messages by the JMSContext's connection.
public void	unsubscribe(String the name used to identify this subscription name) Unsubscribes a durable subscription that has been created by a client.

public Interface JMSContext

Field Summary

Method Summary