|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
A JMS Session is a single threaded context for producing and consuming messages. Although it may allocate provider resources outside the Java virtual machine, it is considered a light-weight JMS object.
A session serves several purposes:
A session can create and service multiple message producers and consumers.
One typical use is to have a thread block on a synchronous MessageConsumer until a message arrives. The thread may then use one or more of the Session's MessageProducers.
If a client desires to have one thread producing messages while others consume them, the client should use a separate Session for its producing thread.
Once a connection has been started, any session with a registered message listener(s) is dedicated to the thread of control that delivers messages to it. It is erroneous for client code to use this session or any of its constituent objects from another thread of control. The only exception to this is the use of the session or connection close method.
It should be easy for most clients to partition their work naturally into Sessions. This model allows clients to start simply and incrementally add message processing complexity as their need for concurrency grows.
The close method is the only session method that can be called while some other session method is being executed in another thread.
A session may be optionally specified as transacted. Each transacted session supports a single series of transactions. Each transaction groups a set of message sends and a set of message receives into an atomic unit of work. In effect, transactions organize a session's input message stream and output message stream into series of atomic units. When a transaction commits, its atomic unit of input is acknowledged and its associated atomic unit of output is sent. If a transaction rollback is done, its sent messages are destroyed and the session's input is automatically recovered.
The content of a transaction's input and output units is simply those messages that have been produced and consumed within the session's current transaction.
A transaction is completed using either its session's
commit
or rollback
method. The completion of a
session's current transaction automatically begins the next. The result
is that a transacted session always has a current transaction within
which its work is done.
JTS, or some other transaction monitor may be used to combine a session's transaction with transactions on other resources (databases, other JMS sessions, etc.). Since Java distributed transactions are controlled via JTA, use of the session's commit and rollback methods in this context is prohibited.
JMS does not require support for JTA; however, it does define how a provider supplies this support.
Although it is also possible for a JMS client to handle distributed transactions directly, it is unlikely that many JMS clients will do this. Support for JTA in JMS is targeted at systems vendors who will be integrating JMS into their application server products.
QueueSession
,
TopicSession
,
XASession
Field Summary | |
static int |
AUTO_ACKNOWLEDGE
With this acknowledgement mode, the session automatically acknowledges a client's receipt of a message when it has either successfully returned from a call to receive or the message listener it has called to process the message successfully returns. |
static int |
CLIENT_ACKNOWLEDGE
With this acknowledgement mode, the client acknowledges a message by calling a message's acknowledge method. |
static int |
DUPS_OK_ACKNOWLEDGE
This acknowledgement mode instructs the session to lazily acknowledge the delivery of messages. |
Method Summary | |
void |
close()
Since a provider may allocate some resources on behalf of a Session outside the JVM, clients should close them when they are not needed. |
void |
commit()
Commit all messages done in this transaction and releases any locks currently held. |
BytesMessage |
createBytesMessage()
Create a BytesMessage. |
MapMessage |
createMapMessage()
Create a MapMessage. |
Message |
createMessage()
Create a Message. |
ObjectMessage |
createObjectMessage()
Create an ObjectMessage. |
ObjectMessage |
createObjectMessage(java.io.Serializable object)
Create an initialized ObjectMessage. |
StreamMessage |
createStreamMessage()
Create a StreamMessage. |
TextMessage |
createTextMessage()
Create a TextMessage. |
TextMessage |
createTextMessage(java.lang.String text)
Create an initialized TextMessage. |
MessageListener |
getMessageListener()
Return the session's distinguished message listener (optional). |
boolean |
getTransacted()
Is the session in transacted mode? |
void |
recover()
Stop message delivery in this session, and restart sending messages with the oldest unacknowledged message. |
void |
rollback()
Rollback any messages done in this transaction and releases any locks currently held. |
void |
run()
Only intended to be used by Application Servers (optional operation). |
void |
setMessageListener(MessageListener listener)
Set the session's distinguished message listener (optional). |
Field Detail |
public static final int AUTO_ACKNOWLEDGE
public static final int CLIENT_ACKNOWLEDGE
When client acknowledgment mode is used, a client may build up a large number of unacknowledged messages while attempting to process them. A JMS provider should provide administrators with a way to limit client over-run so that clients are not driven to resource exhaustion and ensuing failure when some resource they are using is temporarily blocked.
public static final int DUPS_OK_ACKNOWLEDGE
Method Detail |
public BytesMessage createBytesMessage() throws JMSException
public MapMessage createMapMessage() throws JMSException
public Message createMessage() throws JMSException
public ObjectMessage createObjectMessage() throws JMSException
public ObjectMessage createObjectMessage(java.io.Serializable object) throws JMSException
object
- the object to use to initialize this message.public StreamMessage createStreamMessage() throws JMSException
public TextMessage createTextMessage() throws JMSException
public TextMessage createTextMessage(java.lang.String text) throws JMSException
text
- the string used to initialize this message.public boolean getTransacted() throws JMSException
public void commit() throws JMSException
public void rollback() throws JMSException
public void close() throws JMSException
There is no need to close the producers and consumers of a closed session.
This call will block until a receive or message listener in progress has completed. A blocked message consumer receive call returns null when this session is closed.
Closing a transacted session must rollback the in-progress transaction.
This method is the only session method that can be concurrently called.
Invoking any other session method on a closed session must throw JMSException.IllegalStateException. Closing a closed session must NOT throw an exception.
public void recover() throws JMSException
All consumers deliver messages in a serial order. Acknowledging a received message automatically acknowledges all messages that have been delivered to the client.
Restarting a session causes it to take the following actions:
Redelivered messages do not have to be delivered in exactly their original delivery order.
public MessageListener getMessageListener() throws JMSException
setMessageListener(javax.jms.MessageListener)
,
ServerSessionPool
,
ServerSession
public void setMessageListener(MessageListener listener) throws JMSException
listener
- the message listener to associate with this session.getMessageListener()
,
ServerSessionPool
,
ServerSession
public void run()
ServerSession
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |