com.ibm.mq.jms
Class MQSession

java.lang.Object
  |
  +--com.ibm.mq.jms.MQSession
All Implemented Interfaces:
JMSAcknowledgePoint, JMSDestinationFactory, java.lang.Runnable, javax.jms.Session
Direct Known Subclasses:
MQQueueSession, MQTopicSession, MQXASession

public class MQSession
extends java.lang.Object
implements javax.jms.Session, JMSAcknowledgePoint, JMSDestinationFactory

A JMS session is a single-threaded context for producing and consuming messages.


Field Summary
 
Fields inherited from interface javax.jms.Session
AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE, SESSION_TRANSACTED
     
Method Summary
 void close()
          Closes the session.
 void commit()
          Commits 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()
          Creates a BytesMessage object.
 javax.jms.MessageConsumer createConsumer(javax.jms.Destination destination)
          Creates a MessageConsumer for the specified Destination.
 javax.jms.MessageConsumer createConsumer(javax.jms.Destination destination, java.lang.String messageSelector)
          Creates a MessageConsumer for the specified Destination, using a message selector.
 javax.jms.MessageConsumer createConsumer(javax.jms.Destination destination, java.lang.String messageSelector, boolean noLocal)
          Creates MessageConsumer for the specified destination, using a message selector.
 javax.jms.TopicSubscriber createDurableSubscriber(javax.jms.Topic topic, java.lang.String name)
          Creates a durable Subscriber to the specified topic.
 javax.jms.TopicSubscriber createDurableSubscriber(javax.jms.Topic topic, java.lang.String name, java.lang.String selector, boolean noLocal)
          Creates a durable Subscriber to the specified topic.
 javax.jms.MapMessage createMapMessage()
          Creates a MapMessage.
 javax.jms.Message createMessage()
          Creates a Message.
 javax.jms.ObjectMessage createObjectMessage()
          Creates an ObjectMessage.
 javax.jms.ObjectMessage createObjectMessage(java.io.Serializable object)
          Creates an initialized ObjectMessage.
 javax.jms.MessageProducer createProducer(javax.jms.Destination destination)
          Creates a MessageProducer to send messages to the specified destination.
 javax.jms.Queue createQueue(java.lang.String queueName)
          Creates a queue object given a queue name.
 javax.jms.StreamMessage createStreamMessage()
          Creates a StreamMessage object.
 javax.jms.TemporaryQueue createTemporaryQueue()
          Creates a JMS temporary queue.
 javax.jms.TemporaryTopic createTemporaryTopic()
          Creates a temporary topic.
 javax.jms.TextMessage createTextMessage()
          Creates a TextMessage.
 javax.jms.TextMessage createTextMessage(java.lang.String string)
          Creates an initialized TextMessage.
 javax.jms.Topic createTopic(java.lang.String topicName)
          Creates a Topic given a Topic name.
 int getAcknowledgeMode()
          Gets the acknowledgement mode of the session.
 javax.jms.MessageListener getMessageListener()
          Gets the session's distinguished message listener.
 boolean getTransacted()
          Indicates whether the session is in transacted mode.
 void recover()
          Stops message delivery in this session and restarts message delivery with the oldest unacknowledged message.
 void rollback()
          Rolls back any messages processed in this transaction and releases any locks currently held.
 void setMessageListener(javax.jms.MessageListener listener)
          Sets the session's distinguished message listener.
 void unsubscribe(java.lang.String name)
          Unsubscribes a durable subscription that has been created by a client.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

commit

public void commit()
            throws javax.jms.JMSException
Commits all messages done in this transaction and releases any locks currently held. This always throws a JMSException when you have a direct connection to WebSphere MQ Event Broker.

Specified by:
commit in interface javax.jms.Session
Throws:
javax.jms.JMSException - with one of the following reasons:

recover

public void recover()
             throws javax.jms.JMSException
Stops message delivery in this session and restarts message delivery with the oldest unacknowledged message. This always throws a JMSException when you have a direct connection to a broker.

Specified by:
recover in interface javax.jms.Session
Throws:
javax.jms.JMSException - with one of the following reasons:

rollback

public void rollback()
              throws javax.jms.JMSException
Rolls back any messages processed in this transaction and releases any locks currently held. This always throws a JMSException when you have a direct connection to a broker.

Specified by:
rollback in interface javax.jms.Session
Throws:
javax.jms.JMSException - with one of the following reasons:

close

public void close()
           throws javax.jms.JMSException
Closes the session.

Specified by:
close in interface javax.jms.Session
Throws:
javax.jms.JMSException - with one of the following reasons:

createBytesMessage

public javax.jms.BytesMessage createBytesMessage()
                                          throws javax.jms.JMSException
Creates a BytesMessage object.

Specified by:
createBytesMessage in interface javax.jms.Session
Returns:
BytesMessage
Throws:
javax.jms.JMSException - if JMS fails due to some internal JMS error.
javax.jms.JMSException - with reason MQJMS_E_SESSION_CLOSED.

createMapMessage

public javax.jms.MapMessage createMapMessage()
                                      throws javax.jms.JMSException
Creates 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:
MapMessage
Throws:
javax.jms.JMSException - with reason MQJMS_E_SESSION_CLOSED

createMessage

public javax.jms.Message createMessage()
                                throws javax.jms.JMSException
Creates 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:
Message
Throws:
javax.jms.JMSException - with reason MQJMS_E_SESSION_CLOSED.

createObjectMessage

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

Specified by:
createObjectMessage in interface javax.jms.Session
Returns:
ObjectMessage
Throws:
javax.jms.IllegalStateException - with reason MQJMS_E_SESSION_CLOSED.
javax.jms.JMSException

createObjectMessage

public javax.jms.ObjectMessage createObjectMessage(java.io.Serializable object)
                                            throws javax.jms.JMSException
Creates 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:
ObjectMessage
Throws:
javax.jms.IllegalStateException - with reason MQJMS_E_SESSION_CLOSED.
javax.jms.JMSException

createStreamMessage

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

Specified by:
createStreamMessage in interface javax.jms.Session
Returns:
StreamMessage
Throws:
javax.jms.JMSException - IllegalStateException with reason MQJMS_E_SESSION_CLOSED.

createTextMessage

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

Specified by:
createTextMessage in interface javax.jms.Session
Returns:
TextMessage
Throws:
javax.jms.JMSException - IllegalStateException with reason MQJMS_E_SESSION_CLOSED.

createTextMessage

public javax.jms.TextMessage createTextMessage(java.lang.String string)
                                        throws javax.jms.JMSException
Creates an initialized TextMessage.

Specified by:
createTextMessage in interface javax.jms.Session
Parameters:
string - the string used to initialize this message.
Returns:
TextMessage
Throws:
javax.jms.JMSException - IllegalStateException with reason MQJMS_E_SESSION_CLOSED.

getTransacted

public boolean getTransacted()
                      throws javax.jms.JMSException
Indicates whether the session is in transacted mode. Always returns false when you have a direct connection to a broker.

Specified by:
getTransacted in interface javax.jms.Session
Returns:
true if in transacted mode
Throws:
javax.jms.JMSException - with one of the following reasons:

getMessageListener

public javax.jms.MessageListener getMessageListener()
                                             throws javax.jms.JMSException
Gets the session's distinguished message listener.

Specified by:
getMessageListener in interface javax.jms.Session
Returns:
MessageListener
Throws:
javax.jms.JMSException - with reason MQJMS_E_SESSION_CLOSED.

setMessageListener

public void setMessageListener(javax.jms.MessageListener listener)
                        throws javax.jms.JMSException
Sets the session's distinguished message listener.

Specified by:
setMessageListener in interface javax.jms.Session
Parameters:
listener -
Throws:
javax.jms.JMSException - with one of the following reasons:

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.

Specified by:
createBrowser in interface javax.jms.Session
Parameters:
queue - the queue to access.
Returns:
a newly created QueueBrowser
Throws:
javax.jms.JMSException - with one of the following reasons:
Since:
JMS 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.

Specified by:
createBrowser in interface javax.jms.Session
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.
Returns:
a newly created QueueBrowser
Throws:
javax.jms.JMSException - with one of the following reasons:
Since:
JMS 1.1

createQueue

public javax.jms.Queue createQueue(java.lang.String queueName)
                            throws javax.jms.JMSException
Creates a queue object given a queue name.

Specified by:
createQueue in interface javax.jms.Session
Parameters:
queueName - the name of the Queue to be created.
Returns:
a Queue of the given name.
Throws:
javax.jms.JMSException - with one of the following reasons:
Since:
JMS 1.1

createTemporaryQueue

public javax.jms.TemporaryQueue createTemporaryQueue()
                                              throws javax.jms.JMSException
Creates a JMS temporary queue. The temporary queue remains until the connection ends or the queue is explicitly deleted, whichever is the sooner.

Specified by:
createTemporaryQueue in interface javax.jms.Session
Returns:
TemporaryQueue
Throws:
javax.jms.JMSException - IllegalStateException with one of the following reasons:
Since:
JMS 1.1

createTopic

public javax.jms.Topic createTopic(java.lang.String topicName)
                            throws javax.jms.JMSException
Creates a Topic given a Topic name.

Specified by:
createTopic in interface javax.jms.Session
Parameters:
topicName - the name of this topic
Returns:
a Topic with the given name.
Throws:
javax.jms.JMSException - if a Session fails to create a Topic due to an internal error.
javax.jms.IllegalStateException - if the Session object has been closed.
Since:
JMS 1.1

createDurableSubscriber

public javax.jms.TopicSubscriber createDurableSubscriber(javax.jms.Topic topic,
                                                         java.lang.String name)
                                                  throws javax.jms.JMSException
Creates a durable Subscriber to the specified topic.

Specified by:
createDurableSubscriber in interface javax.jms.Session
Parameters:
topic - the topic to subscribe to
name - the name used to identify this subscription.
Returns:
the topic subscriber
Throws:
javax.jms.IllegalStateException - if the session has been closed.
javax.jms.InvalidDestinationException - if the topic specified is not valid.
javax.jms.JMSException - if the Session fails to create a subscriber due to an internal error.
Since:
JMS 1.1

createDurableSubscriber

public javax.jms.TopicSubscriber createDurableSubscriber(javax.jms.Topic topic,
                                                         java.lang.String name,
                                                         java.lang.String selector,
                                                         boolean noLocal)
                                                  throws javax.jms.JMSException
Creates a durable Subscriber to the specified topic.

Specified by:
createDurableSubscriber in interface javax.jms.Session
Parameters:
topic - the topic to subscribe to
name - the name used to identify this subscription.
selector - only messages with properties matching the message selector expression are delivered. This value may be null.
noLocal - true inhibits the delivery of messages published by its own connection.
Throws:
javax.jms.IllegalStateException - if the session has been closed.
javax.jms.InvalidDestinationException - if the topic specified is not valid.
javax.jms.JMSException - if the Session fails to create a subscriber due to an internal error.
Since:
JMS 1.1

createTemporaryTopic

public javax.jms.TemporaryTopic createTemporaryTopic()
                                              throws javax.jms.JMSException
Creates a temporary topic. The temporary topic remains until the connection ends or the topic is explicitly deleted, whichever is the sooner.

Specified by:
createTemporaryTopic in interface javax.jms.Session
Returns:
a temporary topic.
Throws:
javax.jms.JMSException - if the Session fails to create a temporary topic due to an internal error.
javax.jms.IllegalStateException - if the Session object has been closed.
Since:
JMS 1.1

createConsumer

public javax.jms.MessageConsumer createConsumer(javax.jms.Destination destination)
                                         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.

Specified by:
createConsumer in interface javax.jms.Session
Parameters:
destination - the Destination to access.
Returns:
the message consumer
Throws:
javax.jms.JMSException - if the command fails due to some internal JMS error.
Since:
JMS 1.1

createConsumer

public javax.jms.MessageConsumer createConsumer(javax.jms.Destination destination,
                                                java.lang.String messageSelector)
                                         throws javax.jms.JMSException
Creates a MessageConsumer for the specified Destination, using a message selector.

Specified by:
createConsumer in interface javax.jms.Session
Parameters:
destination - the Destination to access.
messageSelector - the message selector
Returns:
the message consumer.
Throws:
javax.jms.JMSException - if the command fails due to some internal JMS error.

createConsumer

public javax.jms.MessageConsumer createConsumer(javax.jms.Destination destination,
                                                java.lang.String messageSelector,
                                                boolean noLocal)
                                         throws javax.jms.JMSException
Creates MessageConsumer for the specified destination, using a message selector.

Specified by:
createConsumer in interface javax.jms.Session
Parameters:
destination - the Destination to access.
messageSelector - the message selector
noLocal - when the destination is a topic, true inhibits the delivery of messages published by its own connection. The behavior for NoLocal is ignored if the destination is a queue.
Returns:
MessageConsumer
Throws:
javax.jms.JMSException - with linked exception InvalidDestinationException with reason MQJMS_EXCEPTION_INVALID_DESTINATION.
javax.jms.JMSException - with linked exception to whatever createQConsumer, createTConsumer and addConsumer throw.
Since:
JMS 1.1

createProducer

public javax.jms.MessageProducer createProducer(javax.jms.Destination destination)
                                         throws javax.jms.JMSException
Creates a MessageProducer to send messages to the specified destination.

Specified by:
createProducer in interface javax.jms.Session
Parameters:
destination - the Destination to send to, or null if this is a producer which does not have a specified destination.
Throws:
javax.jms.JMSException - with reason MQJMS_EXCEPTION_MQ_NULL_QMGR
javax.jms.JMSException - with reason MQJMS_EXCEPTION_MQ_Q_OPEN_FAILED
javax.jms.InvalidDestinationException - If the topic specified is not valid.
javax.jms.JMSException - if the Session fails to create a producer because of an internal error.
Since:
JMS 1.1

getAcknowledgeMode

public final int getAcknowledgeMode()
                             throws javax.jms.JMSException
Gets the acknowledgement mode of the session. The acknowledgement mode is set at the time that the session is created.

Specified by:
getAcknowledgeMode in interface javax.jms.Session
Returns:
the current acknowledgement mode for the session if the session is not transacted. Otherwise returns SESSION_TRANSACTED.
javax.jms.JMSException
Since:
JMS 1.1

unsubscribe

public void unsubscribe(java.lang.String name)
                 throws javax.jms.JMSException
Unsubscribes a durable subscription that has been created by a client.

For a direct connection to WebSphere MQ Event Broker, WebSphere Business Integration Event Broker, or WebSphere Business Integration Message Broker, this method throws a JMSException.

Specified by:
unsubscribe in interface javax.jms.Session
Throws:
javax.jms.JMSException - if the Session fails to unsubscribe to the durable subscription due to an internal error.
Since:
JMS 1.1

(c) Copyright IBM Corp. 2005. All Rights Reserved.