|
Websphere MQ Everyplace | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.ibm.mqe.jms.MQeSession
A JMS Session
is a single threaded context for producing and consuming
messages. 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 MessageProducer
s.
If a client desires to have one thread produce 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 one or more
registered message listeners 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 rule is the use of the session or connection
close
method.
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.
A Session may be used by more than one thread, but should not be used concurrently by multiple threads. If a Session is shared by multiple threads then the user application must provide explicit thread synchronization to ensure that this concurrency restriction is met. Failure to do this may result in unexpected behaviour, and it is recommended that Sessions are only used by one thread.
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. |
javax.jms.QueueBrowser |
createBrowser(javax.jms.Queue queue)
Creates a QueueBrowser object to peek at the messages on
the specified queue. |
javax.jms.QueueBrowser |
createBrowser(javax.jms.Queue queue,
java.lang.String messageSelector)
Creates a QueueBrowser object to peek at the messages on
the specified queue using a message selector. |
javax.jms.BytesMessage |
createBytesMessage()
Create a BytesMessage. |
javax.jms.MessageConsumer |
createConsumer(javax.jms.Destination dest)
Creates a MessageConsumer for the specified destination. |
javax.jms.MessageConsumer |
createConsumer(javax.jms.Destination dest,
java.lang.String messageSelector)
Creates a MessageConsumer for the specified destination,
using a message selector. |
javax.jms.MessageConsumer |
createConsumer(javax.jms.Destination dest,
java.lang.String messageSelector,
boolean um)
Creates MessageConsumer for the specified destination, using a
message selector. |
javax.jms.MapMessage |
createMapMessage()
Create a MapMessage. |
javax.jms.Message |
createMessage()
Create a Message. |
javax.jms.ObjectMessage |
createObjectMessage()
Create an ObjectMessage. |
javax.jms.ObjectMessage |
createObjectMessage(java.io.Serializable object)
Create an initialized ObjectMessage. |
javax.jms.MessageProducer |
createProducer(javax.jms.Destination dest)
Creates a MessageProducer to send messages to the specified
destination. |
javax.jms.Queue |
createQueue(java.lang.String queueName)
Creates a queue identity given a Queue name. |
javax.jms.StreamMessage |
createStreamMessage()
Create a StreamMessage. |
javax.jms.TemporaryQueue |
createTemporaryQueue()
Creates a TemporaryQueue object. |
javax.jms.TextMessage |
createTextMessage()
Create a TextMessage. |
javax.jms.TextMessage |
createTextMessage(java.lang.String string)
Create an initialized TextMessage. |
int |
getAcknowledgementMode()
Deprecated. since JMS 1.1, getAcknowledgeMode() should be used |
int |
getAcknowledgeMode()
Returns the acknowledgement mode of the session. |
javax.jms.MessageListener |
getMessageListener()
Return the session's distinguished message listener. |
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 |
setMessageListener(javax.jms.MessageListener listener)
Set the session's distinguished message listener. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Methods inherited from interface javax.jms.Session |
run |
Field Detail |
public static final int AUTO_ACKNOWLEDGE
public static final int CLIENT_ACKNOWLEDGE
public static final int DUPS_OK_ACKNOWLEDGE
Method Detail |
public javax.jms.BytesMessage createBytesMessage() throws javax.jms.JMSException
createBytesMessage
in interface javax.jms.Session
javax.jms.JMSException
- if JMS fails to create this message
due to some internal error.public javax.jms.MapMessage createMapMessage() throws javax.jms.JMSException
createMapMessage
in interface javax.jms.Session
javax.jms.JMSException
- if JMS fails to create this message
due to some internal error.public javax.jms.Message createMessage() throws javax.jms.JMSException
createMessage
in interface javax.jms.Session
javax.jms.JMSException
- if JMS fails to create this message
due to some internal error.public javax.jms.ObjectMessage createObjectMessage() throws javax.jms.JMSException
createObjectMessage
in interface javax.jms.Session
javax.jms.JMSException
- if JMS fails to create this message
due to some internal error.public javax.jms.ObjectMessage createObjectMessage(java.io.Serializable object) throws javax.jms.JMSException
createObjectMessage
in interface javax.jms.Session
object
- the object to use to initialize this message.
javax.jms.JMSException
- if JMS fails to create this message
due to some internal error.public javax.jms.StreamMessage createStreamMessage() throws javax.jms.JMSException
createStreamMessage
in interface javax.jms.Session
javax.jms.JMSException
- if JMS fails to create this message
due to some internal error.public javax.jms.TextMessage createTextMessage() throws javax.jms.JMSException
createTextMessage
in interface javax.jms.Session
javax.jms.JMSException
- if JMS fails to create this message
due to some internal error.public javax.jms.TextMessage createTextMessage(java.lang.String string) throws javax.jms.JMSException
createTextMessage
in interface javax.jms.Session
string
- the string used to initialize this message.
javax.jms.JMSException
- if JMS fails to create this message
due to some internal error.public boolean getTransacted() throws javax.jms.JMSException
getTransacted
in interface javax.jms.Session
javax.jms.JMSException
- if JMS fails to return the transaction
mode due to internal error in JMS Provider.public void commit() throws javax.jms.JMSException
commit
in interface javax.jms.Session
javax.jms.JMSException
- if JMS implementation fails to commit the
the transaction due to some internal error.
javax.jms.TransactionRolledBackException
- if the transaction
gets rolled back due to some internal error
during commit.
javax.jms.IllegalStateException
- if the session is closed or if an async
listener is using the session thread.public void rollback() throws javax.jms.JMSException
rollback
in interface javax.jms.Session
javax.jms.JMSException
- if JMS implementation fails to rollback the
the transaction due to some internal error.public void close() throws javax.jms.JMSException
This method should not be invoked from within
javax.jms.MessageListener#onMessage()
.
close
in interface javax.jms.Session
javax.jms.JMSException
- if JMS implementation fails to close a
Session due to some internal error.public void recover() throws javax.jms.JMSException
recover
in interface javax.jms.Session
javax.jms.JMSException
- if JMS implementation fails to stop message
delivery and restart message send due to
due to some internal error.public javax.jms.MessageListener getMessageListener() throws javax.jms.JMSException
getMessageListener
in interface javax.jms.Session
javax.jms.JMSException
- as this method is not supported.
public void setMessageListener(javax.jms.MessageListener listener) throws javax.jms.JMSException
setMessageListener
in interface javax.jms.Session
javax.jms.JMSException
- as this method is not supported.
public int getAcknowledgeMode() throws javax.jms.JMSException
javax.jms.JMSException
- if the JMS provider fails to return the
acknowledgment mode due to some internal error.Connection#createSession
public int getAcknowledgementMode()
getAcknowledgeMode()
should be used
public javax.jms.Queue createQueue(java.lang.String queueName) throws javax.jms.JMSException
Queue
name.
This facility is provided for the rare cases where clients need to dynamically manipulate queue identity. It allows the creation of a queue identity with a provider-specific name. Clients that depend on this ability are not portable.
Note that this method is not for creating the physical queue.
The physical creation of queues is an administrative task and is not
to be initiated by the JMS API. The one exception is the
creation of temporary queues, which is accomplished with the
createTemporaryQueue
method.
queueName
- the name of this Queue
Queue
with the given name
javax.jms.JMSException
- if the session fails to create a queue
due to some internal error.public javax.jms.TemporaryQueue createTemporaryQueue() throws javax.jms.JMSException
TemporaryQueue
object. Its lifetime will be that
of the Connection
unless it is deleted earlier.
javax.jms.JMSException
- if the session fails to create a temporary queue
due to some internal error.public javax.jms.QueueBrowser createBrowser(javax.jms.Queue queue) throws javax.jms.JMSException
QueueBrowser
object to peek at the messages on
the specified queue.
queue
- the queue
to access
javax.jms.JMSException
- if the session fails to create a browser
due to some internal error.
javax.jms.InvalidDestinationException
- if an invalid destination
is specifiedpublic javax.jms.QueueBrowser createBrowser(javax.jms.Queue queue, java.lang.String messageSelector) throws javax.jms.JMSException
QueueBrowser
object to peek at the messages on
the specified queue using a message selector.
queue
- the queue
to accessmessageSelector
- 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.
javax.jms.JMSException
- if the session fails to create a browser
due to some internal error.
javax.jms.InvalidDestinationException
- if an invalid destination
is specified
javax.jms.InvalidSelectorException
- if the message selector is invalid.public javax.jms.MessageProducer createProducer(javax.jms.Destination dest) throws javax.jms.JMSException
MessageProducer
to send messages to the specified
destination.
A client uses a MessageProducer
object to send
messages to a destination. Since Queue
and Topic
both inherit from Destination
, they can be used in
the destination parameter to create a MessageProducer
object.
javax.jms.JMSException
- if the session fails to create a MessageProducer
due to some internal error.
javax.jms.InvalidDestinationException
- if an invalid destination
is specified.public javax.jms.MessageConsumer createConsumer(javax.jms.Destination dest) throws javax.jms.JMSException
MessageConsumer
for the specified destination.
Since Queue
and Topic
both inherit from Destination
, they can be used in
the destination parameter to create a MessageConsumer
.
javax.jms.JMSException
- if the session fails to create a consumer
due to some internal error.
javax.jms.InvalidDestinationException
- if an invalid destination
is specified.public javax.jms.MessageConsumer createConsumer(javax.jms.Destination dest, java.lang.String messageSelector) throws javax.jms.JMSException
MessageConsumer
for the specified destination,
using a message selector.
Since Queue
and Topic
both inherit from Destination
, they can be used in
the destination parameter to create a MessageConsumer
.
A client uses a MessageConsumer
object to receive
messages that have been sent to a destination.
messageSelector
- 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.
javax.jms.JMSException
- if the session fails to create a MessageConsumer
due to some internal error.
javax.jms.InvalidDestinationException
- if an invalid destination
is specified.
javax.jms.InvalidSelectorException
- if the message selector is invalid.public javax.jms.MessageConsumer createConsumer(javax.jms.Destination dest, java.lang.String messageSelector, boolean um) throws javax.jms.JMSException
MessageConsumer
for the specified destination, using a
message selector. This method can specify whether messages published by
its own connection should be delivered to it, if the destination is a
topic.
Since Queue
and Topic
both inherit from Destination
, they can be used in
the destination parameter to create a MessageConsumer
.
A client uses a MessageConsumer
object to receive
messages that have been published to a destination.
In some cases, a connection may both publish and subscribe to a
topic. The consumer NoLocal
attribute allows a consumer
to inhibit the delivery of messages published by its own connection.
The default value for this attribute is False. The noLocal
value must be supported by destinations that are topics.
messageSelector
- 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.
javax.jms.JMSException
- if the session fails to create a MessageConsumer
due to some internal error.
javax.jms.InvalidDestinationException
- if an invalid destination
is specified.
javax.jms.InvalidSelectorException
- if the message selector is invalid.
|
Websphere MQ Everyplace | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |