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

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.

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.BytesMessage createBytesMessage()
          Create a BytesMessage.
 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.StreamMessage createStreamMessage()
          Create a StreamMessage.
 javax.jms.TextMessage createTextMessage()
          Create a TextMessage.
 javax.jms.TextMessage createTextMessage(java.lang.String string)
          Create an initialized TextMessage.
 int getAcknowledgementMode()
          get the acknowledgement mode for this 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.

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:

getAcknowledgementMode

public int getAcknowledgementMode()
get the acknowledgement mode for this session. This will be one of AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE or DUPS_OK_ACKNOWLEDGE

Returns:
the acknowledgement mode for this session

Websphere MQ Everyplace