Websphere MQ Everyplace

com.ibm.mqe.jms
Class MQeSession

java.lang.Object
  |
  +--com.ibm.mqe.jms.MQeSession
All Implemented Interfaces:
java.lang.Runnable, javax.jms.Session
Direct Known Subclasses:
MQeQueueSession

public class MQeSession
extends java.lang.Object
implements javax.jms.Session

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 MessageProducers.

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.

See Also:

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

AUTO_ACKNOWLEDGE

public static final 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.

See Also:
Constant Field Values

CLIENT_ACKNOWLEDGE

public static final int CLIENT_ACKNOWLEDGE
With this acknowledgement mode, the client acknowledges a message by calling a message's acknowledge method. Acknowledging a message acknowledges all messages that the Session has consumed.

See Also:
Constant Field Values

DUPS_OK_ACKNOWLEDGE

public static final int DUPS_OK_ACKNOWLEDGE
This acknowledgement mode instructs the session to lazily acknowledge the delivery of messages. This is likely to result in the delivery of some duplicate messages if JMS fails, it should only be used by consumers that are tolerant of duplicate messages.

See Also:
Constant Field Values
Method Detail

createBytesMessage

public javax.jms.BytesMessage createBytesMessage()
                                          throws javax.jms.JMSException
Create a BytesMessage. A BytesMessage is used to send a message containing a stream of uninterpreted bytes.

Specified by:
createBytesMessage in interface javax.jms.Session
Returns:
a BytesMessage
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error.

createMapMessage

public javax.jms.MapMessage createMapMessage()
                                      throws javax.jms.JMSException
Create a MapMessage. A MapMessage is used to send a self-defining set of name-value pairs where names are Strings and values are Java primitive types.

Specified by:
createMapMessage in interface javax.jms.Session
Returns:
a MapMessage
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error.

createMessage

public javax.jms.Message createMessage()
                                throws javax.jms.JMSException
Create a Message. The Message interface is the root interface of all JMS messages. It holds all the standard message header information. It can be sent when a message containing only header information is sufficient.

Specified by:
createMessage in interface javax.jms.Session
Returns:
a Message
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error.

createObjectMessage

public javax.jms.ObjectMessage createObjectMessage()
                                            throws javax.jms.JMSException
Create an ObjectMessage. An ObjectMessage is used to send a message that containing a serializable Java object.

Specified by:
createObjectMessage in interface javax.jms.Session
Returns:
an ObjectMessage
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error.

createObjectMessage

public javax.jms.ObjectMessage createObjectMessage(java.io.Serializable object)
                                            throws javax.jms.JMSException
Create an initialized ObjectMessage. An ObjectMessage is used to send a message that containing a serializable Java object.

Specified by:
createObjectMessage in interface javax.jms.Session
Parameters:
object - the object to use to initialize this message.
Returns:
an ObjectMessage
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error.

createStreamMessage

public javax.jms.StreamMessage createStreamMessage()
                                            throws javax.jms.JMSException
Create a StreamMessage. A StreamMessage is used to send a self-defining stream of Java primitives.

Specified by:
createStreamMessage in interface javax.jms.Session
Returns:
a StreamMessage
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error.

createTextMessage

public javax.jms.TextMessage createTextMessage()
                                        throws javax.jms.JMSException
Create a TextMessage. A TextMessage is used to send a message containing a StringBuffer.

Specified by:
createTextMessage in interface javax.jms.Session
Returns:
a TextMessage
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error.

createTextMessage

public javax.jms.TextMessage createTextMessage(java.lang.String string)
                                        throws javax.jms.JMSException
Create an initialized TextMessage. A TextMessage is used to send a message containing a StringBuffer.

Specified by:
createTextMessage in interface javax.jms.Session
Parameters:
string - the string used to initialize this message.
Returns:
a TextMessage
Throws:
javax.jms.JMSException - if JMS fails to create this message due to some internal error.

getTransacted

public boolean getTransacted()
                      throws javax.jms.JMSException
Is the session in transacted mode?

Specified by:
getTransacted in interface javax.jms.Session
Returns:
true if in transacted mode
Throws:
javax.jms.JMSException - if JMS fails to return the transaction mode due to internal error in JMS Provider.

commit

public void commit()
            throws javax.jms.JMSException
Commit all messages done in this transaction and releases any locks currently held.

Specified by:
commit in interface javax.jms.Session
Throws:
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.

rollback

public void rollback()
              throws javax.jms.JMSException
Rollback any messages done in this transaction and releases any locks currently held.

Specified by:
rollback in interface javax.jms.Session
Throws:
javax.jms.JMSException - if JMS implementation fails to rollback the the transaction due to some internal error.

close

public void close()
           throws javax.jms.JMSException
Since a provider may allocate some resources on behalf of a Session outside the JVM, clients should close them when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough.

This method should not be invoked from within javax.jms.MessageListener#onMessage().

Specified by:
close in interface javax.jms.Session
Throws:
javax.jms.JMSException - if JMS implementation fails to close a Session due to some internal error.

recover

public void recover()
             throws javax.jms.JMSException
Stop message delivery in this session, and restart sending messages with the oldest unacknowledged message.

Specified by:
recover in interface javax.jms.Session
Throws:
javax.jms.JMSException - if JMS implementation fails to stop message delivery and restart message send due to due to some internal error.

getMessageListener

public javax.jms.MessageListener getMessageListener()
                                             throws javax.jms.JMSException
Return the session's distinguished message listener. This method is intended for use by application servers, and is not supported by WebSphere MQ Everyplace v2.0

Specified by:
getMessageListener in interface javax.jms.Session
Throws:
javax.jms.JMSException - as this method is not supported.
See Also:

setMessageListener

public void setMessageListener(javax.jms.MessageListener listener)
                        throws javax.jms.JMSException
Set the session's distinguished message listener. This method is intended for use by application servers, and is not supported by WebSphere MQ Everyplace v2.0

Specified by:
setMessageListener in interface javax.jms.Session
Throws:
javax.jms.JMSException - as this method is not supported.
See Also:

getAcknowledgeMode

public int getAcknowledgeMode()
                       throws javax.jms.JMSException
Returns the acknowledgement mode of the session. The acknowledgement mode is set at the time that the session is created. If the session is transacted, the acknowledgement mode is ignored.

Returns:
If the session is not transacted, returns the current acknowledgement mode for the session. If the session is transacted, returns SESSION_TRANSACTED.
Throws:
javax.jms.JMSException - if the JMS provider fails to return the acknowledgment mode due to some internal error.
Since:
1.1
See Also:
Connection#createSession

getAcknowledgementMode

public int getAcknowledgementMode()
Deprecated. since JMS 1.1, getAcknowledgeMode() should be used

get the acknowledgement mode for this session.

Returns:
the acknowledgement mode for this session

createQueue

public javax.jms.Queue createQueue(java.lang.String queueName)
                            throws javax.jms.JMSException
Creates a queue identity given a 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.

Parameters:
queueName - the name of this Queue
Returns:
a Queue with the given name
Throws:
javax.jms.JMSException - if the session fails to create a queue due to some internal error.
Since:
1.1

createTemporaryQueue

public javax.jms.TemporaryQueue createTemporaryQueue()
                                              throws javax.jms.JMSException
Creates a TemporaryQueue object. Its lifetime will be that of the Connection unless it is deleted earlier.

Returns:
a temporary queue identity
Throws:
javax.jms.JMSException - if the session fails to create a temporary queue due to some internal error.
Since:
1.1

createBrowser

public javax.jms.QueueBrowser createBrowser(javax.jms.Queue queue)
                                     throws javax.jms.JMSException
Creates a QueueBrowser object to peek at the messages on the specified queue.

Parameters:
queue - the queue to access
Throws:
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
Since:
1.1

createBrowser

public javax.jms.QueueBrowser createBrowser(javax.jms.Queue queue,
                                            java.lang.String messageSelector)
                                     throws javax.jms.JMSException
Creates a QueueBrowser object to peek at the messages on the specified queue using a message selector.

Parameters:
queue - the queue to access
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.
Throws:
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.
Since:
1.1

createProducer

public javax.jms.MessageProducer createProducer(javax.jms.Destination dest)
                                         throws javax.jms.JMSException
Creates a 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.

Throws:
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.
Since:
1.1

createConsumer

public javax.jms.MessageConsumer createConsumer(javax.jms.Destination dest)
                                         throws javax.jms.JMSException
Creates a 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.

Throws:
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.
Since:
1.1

createConsumer

public javax.jms.MessageConsumer createConsumer(javax.jms.Destination dest,
                                                java.lang.String messageSelector)
                                         throws javax.jms.JMSException
Creates a 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.

Parameters:
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.
Throws:
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.
Since:
1.1

createConsumer

public javax.jms.MessageConsumer createConsumer(javax.jms.Destination dest,
                                                java.lang.String messageSelector,
                                                boolean um)
                                         throws javax.jms.JMSException
Creates 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.

Parameters:
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.
Throws:
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.
Since:
1.1

Websphere MQ Everyplace