public class JMSContext extends Object implements javax.jms.JMSContext
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.
Modifier and Type | Field and Description |
---|---|
private ContextConnection |
connection |
static org.objectweb.util.monolog.api.Logger |
logger |
private Session |
session |
Constructor and Description |
---|
JMSContext(javax.jms.Connection cnx)
Creates a new Context using a newly created JMS connection.
|
JMSContext(javax.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.
|
Modifier and Type | Method and Description |
---|---|
void |
acknowledge() |
void |
close()
API method.
|
void |
commit() |
javax.jms.QueueBrowser |
createBrowser(javax.jms.Queue queue) |
javax.jms.QueueBrowser |
createBrowser(javax.jms.Queue queue,
String messageSelector) |
javax.jms.BytesMessage |
createBytesMessage() |
javax.jms.JMSConsumer |
createConsumer(javax.jms.Destination destination) |
javax.jms.JMSConsumer |
createConsumer(javax.jms.Destination destination,
String selector) |
javax.jms.JMSConsumer |
createConsumer(javax.jms.Destination destination,
String selector,
boolean noLocal) |
javax.jms.JMSContext |
createContext(int sessionMode)
API method.
|
javax.jms.JMSConsumer |
createDurableConsumer(javax.jms.Topic topic,
String name) |
JMSConsumer |
createDurableConsumer(javax.jms.Topic topic,
String name,
String selector,
boolean noLocal) |
javax.jms.MapMessage |
createMapMessage() |
javax.jms.Message |
createMessage() |
javax.jms.ObjectMessage |
createObjectMessage() |
javax.jms.ObjectMessage |
createObjectMessage(Serializable object) |
JMSProducer |
createProducer() |
javax.jms.Queue |
createQueue(String name) |
javax.jms.JMSConsumer |
createSharedConsumer(javax.jms.Topic topic,
String sharedSubscriptionName) |
javax.jms.JMSConsumer |
createSharedConsumer(javax.jms.Topic topic,
String sharedSubscriptionName,
String messageSelector) |
javax.jms.JMSConsumer |
createSharedDurableConsumer(javax.jms.Topic topic,
String name) |
javax.jms.JMSConsumer |
createSharedDurableConsumer(javax.jms.Topic topic,
String name,
String messageSelector) |
javax.jms.StreamMessage |
createStreamMessage() |
javax.jms.TemporaryQueue |
createTemporaryQueue() |
javax.jms.TemporaryTopic |
createTemporaryTopic() |
javax.jms.TextMessage |
createTextMessage() |
javax.jms.TextMessage |
createTextMessage(String text) |
javax.jms.Topic |
createTopic(String name) |
boolean |
getAutoStart() |
String |
getClientID() |
private Session |
getCopyOfSession() |
javax.jms.ExceptionListener |
getExceptionListener() |
javax.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(javax.jms.ExceptionListener listener) |
void |
start() |
void |
stop()
Temporarily stops the delivery of incoming messages by the JMSContext's
connection.
|
void |
unsubscribe(String name) |
public static org.objectweb.util.monolog.api.Logger logger
private ContextConnection connection
private Session session
public JMSContext(ContextConnection connection, int sessionMode)
connection
- the connection of the calling context.sessionMode
- indicates which of four possible session modes will be used.public JMSContext(javax.jms.Connection cnx)
cnx
- the created JMS connection.public JMSContext(javax.jms.Connection cnx, int sessionMode)
cnx
- the created JMS connection.sessionMode
- indicates which of four possible session modes will be used.public javax.jms.JMSContext createContext(int sessionMode)
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.
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.
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.
createContext
in interface javax.jms.JMSContext
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
.javax.jms.JMSRuntimeException
- if the JMS provider fails to create the JMSContext due to
JMSContext.SESSION_TRANSACTED
,
JMSContext.CLIENT_ACKNOWLEDGE
,
JMSContext.AUTO_ACKNOWLEDGE
,
JMSContext.DUPS_OK_ACKNOWLEDGE
,
javax.jms.ConnectionFactory#createContext()
,
javax.jms.ConnectionFactory#createContext(int)
,
javax.jms.ConnectionFactory#createContext(java.lang.String,
java.lang.String)
,
javax.jms.ConnectionFactory#createContext(java.lang.String,
java.lang.String, int)
,
JMSContext.createContext(int)
public void close()
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.
close
in interface AutoCloseable
close
in interface javax.jms.JMSContext
javax.jms.IllegalStateRuntimeException
- JMSContext
is container-managed (injected)javax.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.public void acknowledge()
acknowledge
in interface javax.jms.JMSContext
public void commit()
commit
in interface javax.jms.JMSContext
public void recover()
recover
in interface javax.jms.JMSContext
public void rollback()
rollback
in interface javax.jms.JMSContext
public javax.jms.Message createMessage()
createMessage
in interface javax.jms.JMSContext
public javax.jms.BytesMessage createBytesMessage()
createBytesMessage
in interface javax.jms.JMSContext
public javax.jms.MapMessage createMapMessage()
createMapMessage
in interface javax.jms.JMSContext
public javax.jms.ObjectMessage createObjectMessage()
createObjectMessage
in interface javax.jms.JMSContext
public javax.jms.ObjectMessage createObjectMessage(Serializable object)
createObjectMessage
in interface javax.jms.JMSContext
public javax.jms.TextMessage createTextMessage()
createTextMessage
in interface javax.jms.JMSContext
public javax.jms.TextMessage createTextMessage(String text)
createTextMessage
in interface javax.jms.JMSContext
public javax.jms.StreamMessage createStreamMessage()
createStreamMessage
in interface javax.jms.JMSContext
public javax.jms.TemporaryQueue createTemporaryQueue()
createTemporaryQueue
in interface javax.jms.JMSContext
public javax.jms.TemporaryTopic createTemporaryTopic()
createTemporaryTopic
in interface javax.jms.JMSContext
public javax.jms.Queue createQueue(String name)
createQueue
in interface javax.jms.JMSContext
public javax.jms.Topic createTopic(String name)
createTopic
in interface javax.jms.JMSContext
public boolean getAutoStart()
getAutoStart
in interface javax.jms.JMSContext
public void setAutoStart(boolean autoStart)
setAutoStart
in interface javax.jms.JMSContext
public javax.jms.JMSConsumer createConsumer(javax.jms.Destination destination)
createConsumer
in interface javax.jms.JMSContext
public javax.jms.JMSConsumer createConsumer(javax.jms.Destination destination, String selector)
createConsumer
in interface javax.jms.JMSContext
public javax.jms.JMSConsumer createConsumer(javax.jms.Destination destination, String selector, boolean noLocal)
createConsumer
in interface javax.jms.JMSContext
public javax.jms.QueueBrowser createBrowser(javax.jms.Queue queue)
createBrowser
in interface javax.jms.JMSContext
public javax.jms.QueueBrowser createBrowser(javax.jms.Queue queue, String messageSelector)
createBrowser
in interface javax.jms.JMSContext
public javax.jms.JMSConsumer createDurableConsumer(javax.jms.Topic topic, String name)
createDurableConsumer
in interface javax.jms.JMSContext
public JMSConsumer createDurableConsumer(javax.jms.Topic topic, String name, String selector, boolean noLocal)
createDurableConsumer
in interface javax.jms.JMSContext
public JMSProducer createProducer()
createProducer
in interface javax.jms.JMSContext
public javax.jms.JMSConsumer createSharedConsumer(javax.jms.Topic topic, String sharedSubscriptionName)
createSharedConsumer
in interface javax.jms.JMSContext
public javax.jms.JMSConsumer createSharedConsumer(javax.jms.Topic topic, String sharedSubscriptionName, String messageSelector)
createSharedConsumer
in interface javax.jms.JMSContext
public javax.jms.JMSConsumer createSharedDurableConsumer(javax.jms.Topic topic, String name)
createSharedDurableConsumer
in interface javax.jms.JMSContext
public javax.jms.JMSConsumer createSharedDurableConsumer(javax.jms.Topic topic, String name, String messageSelector)
createSharedDurableConsumer
in interface javax.jms.JMSContext
private Session getCopyOfSession()
public int getSessionMode()
If a session mode was not specified when the JMSContext was created a value of JMSContext.AUTO_ACKNOWLEDGE will be returned.
getSessionMode
in interface javax.jms.JMSContext
javax.jms.JMSRuntimeException
- if the JMS provider fails to return the acknowledgment
mode due to some internal error.Connection.createSession(boolean, int)
public boolean getTransacted()
getTransacted
in interface javax.jms.JMSContext
public javax.jms.ConnectionMetaData getMetaData()
getMetaData
in interface javax.jms.JMSContext
public String getClientID()
getClientID
in interface javax.jms.JMSContext
public void setClientID(String clientID)
setClientID
in interface javax.jms.JMSContext
public javax.jms.ExceptionListener getExceptionListener()
getExceptionListener
in interface javax.jms.JMSContext
public void setExceptionListener(javax.jms.ExceptionListener listener)
setExceptionListener
in interface javax.jms.JMSContext
public void start()
start
in interface javax.jms.JMSContext
public void stop()
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.
stop
in interface javax.jms.JMSContext
javax.jms.IllegalStateRuntimeException
- JMSContext
is container-managed (injected).
javax.jms.JMSRuntimeException
- if the JMS provider fails to stop message delivery for one
of the following reasons:
JMSContext.start()
public void unsubscribe(String name)
unsubscribe
in interface javax.jms.JMSContext
Session getSession()
Copyright © 2018 ScalAgent D.T.. All Rights Reserved.