com.ibm.mq.jms

Class MQSession

java.lang.Object

com.ibm.mq.jms.MQRoot

com.ibm.mq.jms.MQSession

All Implemented Interfaces:

JmsPropertyContext, JmsReadablePropertyContext, JmsSession, java.io.Serializable, java.lang.AutoCloseable, java.lang.Runnable, java.util.Map<java.lang.String,java.lang.Object>, javax.jms.Session

Direct Known Subclasses:

MQQueueSession, MQTopicSession, MQXASession

public class MQSession
extends MQRoot
implements javax.jms.Session, JmsSession

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

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Field Summary

Fields inherited from interface javax.jms.Session

AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE, SESSION_TRANSACTED

Method Summary

Methods

Modifier and Type	Method and Description
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 message consumer for the specified destination.
javax.jms.MessageConsumer	createConsumer(javax.jms.Destination destination, java.lang.String messageSelector) Creates a message consumer for the specified destination, using a message selector.
javax.jms.MessageConsumer	createConsumer(javax.jms.Destination destination, java.lang.String messageSelector, boolean noLocal) Creates a message consumer for the specified destination, using a message selector.
javax.jms.MessageConsumer	createDurableConsumer(javax.jms.Topic topic, java.lang.String name)
javax.jms.MessageConsumer	createDurableConsumer(javax.jms.Topic topic, java.lang.String name, java.lang.String selector, boolean noLocal)
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 destinationP) Creates a message producer 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.MessageConsumer	createSharedConsumer(javax.jms.Topic topic, java.lang.String sharedSubscriptionName)
javax.jms.MessageConsumer	createSharedConsumer(javax.jms.Topic topic, java.lang.String sharedSubscriptionName, java.lang.String messageSelector)
javax.jms.MessageConsumer	createSharedDurableConsumer(javax.jms.Topic topic, java.lang.String sharedSubscriptionName)
javax.jms.MessageConsumer	createSharedDurableConsumer(javax.jms.Topic topic, java.lang.String sharedSubscriptionName, java.lang.String messageSelector)
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.
void	deliver(java.util.List messageReferences)
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 com.ibm.mq.jms.MQRoot

clear, containsKey, containsValue, entrySet, equals, get, getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty, getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty, getObjectProperty, getPropertyNames, getShortProperty, getStringProperty, hashCode, isEmpty, keySet, propertyExists, put, putAll, remove, setBatchProperties, setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty, setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty, setObjectProperty, setShortProperty, setStringProperty, size, values

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.ibm.msg.client.jms.JmsPropertyContext

setBatchProperties, setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty, setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty, setObjectProperty, setShortProperty, setStringProperty

Methods inherited from interface com.ibm.msg.client.jms.JmsReadablePropertyContext

getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty, getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty, getObjectProperty, getPropertyNames, getShortProperty, getStringProperty, propertyExists

Methods inherited from interface java.util.Map

clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, values

Methods inherited from interface javax.jms.Session

run

Method Detail

close

public void close()
           throws javax.jms.JMSException

Closes the session.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface javax.jms.Session

Throws:

javax.jms.JMSException

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 real-time connection to WebSphere MQ Event Broker.

Specified by:

commit in interface javax.jms.Session

Throws:

javax.jms.JMSException

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 queue browser

Throws:

javax.jms.JMSException - if the operation fails

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 queue browser

Throws:

javax.jms.JMSException - if the operation fails

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.

createConsumer

public javax.jms.MessageConsumer createConsumer(javax.jms.Destination destination)
                                         throws javax.jms.JMSException

Creates a message consumer 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.

createConsumer

public javax.jms.MessageConsumer createConsumer(javax.jms.Destination destination,
                                       java.lang.String messageSelector)
                                         throws javax.jms.JMSException

Creates a message consumer 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 a message consumer 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:

the message consumer

Throws:

javax.jms.JMSException - if the operation fails

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:

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

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.

Returns:

the durable subscriber

Throws:

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

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 - if the operation fails

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:

the message

Throws:

javax.jms.JMSException - if the operation fails

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.JMSException - if the operation fails due to some internal error

java.lang.IllegalStateException - if the Session object has been closed

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.JMSException - if the operation fails due to some internal error

java.lang.IllegalStateException - if the Session object has been closed

createProducer

public javax.jms.MessageProducer createProducer(javax.jms.Destination destinationP)
                                         throws javax.jms.JMSException

Creates a message producer to send messages to the specified destination.

Specified by:

createProducer in interface javax.jms.Session

Parameters:

destinationP - the destination to send to, or null if this is a producer which does not have a specified destination

Returns:

the message producer

Throws:

javax.jms.JMSException - if the session fails to create a producer because of an internal error

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 - if the operation fails

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:

the message

Throws:

javax.jms.JMSException - if the operation fails due to some internal error

java.lang.IllegalStateException - if the Session object has been closed.

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.

This session will have been created from a connection that was created from a Connection Factory. If that Connection Factory has a Model Queue defined on it that is a permanent dynamic queue (or the default queue has been modified to have that behaviour), the temporary queue created from this method is only deleted when an explicit MQTemporaryQueue.delete() call is made.

The difference is within the WebSphere Application Server, MQTemporaryQueue.delete() will be called by the application server when a connection is being closed. Therefore even if a permanent dynamic model queue is used, the created temporary queue will be destroyed.

Specified by:

createTemporaryQueue in interface javax.jms.Session

Returns:

the temporary queue

Throws:

javax.jms.JMSException - if the operation fails due to some internal error

java.lang.IllegalStateException - if the Session object has been closed.

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.

java.lang.IllegalStateException - if the Session object has been 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:

the text message

Throws:

javax.jms.JMSException - if the operation fails due to some internal error

java.lang.IllegalStateException - if the Session object has been 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:

the text message

Throws:

javax.jms.JMSException - if the operation fails due to some internal error

java.lang.IllegalStateException - if the Session object has been closed

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

java.lang.IllegalStateException - if the Session object has been closed

getAcknowledgeMode

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

Throws:

javax.jms.JMSException - if the operation fails

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:

the message listener

Throws:

javax.jms.JMSException - if the operation fails due to some internal error

java.lang.IllegalStateException - if the Session object has been closed

getTransacted

public boolean getTransacted()
                      throws javax.jms.JMSException

Indicates whether the session is in transacted mode. Always returns false when you have a real-time connection to a broker.

Specified by:

getTransacted in interface javax.jms.Session

Returns:

true if in transacted mode

Throws:

javax.jms.JMSException - if the operation fails due to some internal error

java.lang.IllegalStateException - if the Session object has been closed

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 real-time connection to a broker.

Specified by:

recover in interface javax.jms.Session

Throws:

javax.jms.JMSException - if the operation fails due to some internal error

java.lang.IllegalStateException - if the Session object has been closed

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 real-time connection to a broker.

Specified by:

rollback in interface javax.jms.Session

Throws:

javax.jms.JMSException - if the operation fails due to some internal error

java.lang.IllegalStateException - if the Session object has been 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 - the listener to set

Throws:

javax.jms.JMSException - if the operation fails

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 real-time 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

Parameters:

name - the name used to identify this subscription

Throws:

javax.jms.JMSException - if the session fails to unsubscribe to the durable subscription due to an internal error.

deliver

public void deliver(java.util.List messageReferences)
             throws javax.jms.JMSException

Parameters:

messageReferences -

Throws:

javax.jms.JMSException

exclude

Deliver a list of message references to this session. This is an ASF method.

createDurableConsumer

public javax.jms.MessageConsumer createDurableConsumer(javax.jms.Topic topic,
                                              java.lang.String name)
                                                throws javax.jms.InvalidDestinationException,
                                                       javax.jms.IllegalStateException,
                                                       javax.jms.JMSException

Specified by:

createDurableConsumer in interface javax.jms.Session

Throws:

javax.jms.InvalidDestinationException

javax.jms.IllegalStateException

javax.jms.JMSException

exclude

Allows a JmsSession to clear any message references that it might have. see com.ibm.msg.client.jms.JmsSession#clearMessageReferences()

createDurableConsumer

public javax.jms.MessageConsumer createDurableConsumer(javax.jms.Topic topic,
                                              java.lang.String name,
                                              java.lang.String selector,
                                              boolean noLocal)
                                                throws javax.jms.InvalidDestinationException,
                                                       javax.jms.InvalidSelectorException,
                                                       javax.jms.IllegalStateException,
                                                       javax.jms.JMSException

Specified by:

createDurableConsumer in interface javax.jms.Session

Throws:

javax.jms.InvalidDestinationException

javax.jms.InvalidSelectorException

javax.jms.IllegalStateException

javax.jms.JMSException

createSharedConsumer

public javax.jms.MessageConsumer createSharedConsumer(javax.jms.Topic topic,
                                             java.lang.String sharedSubscriptionName)
                                               throws javax.jms.JMSException,
                                                      javax.jms.InvalidDestinationException,
                                                      javax.jms.InvalidSelectorException

Specified by:

createSharedConsumer in interface javax.jms.Session

Throws:

javax.jms.JMSException

javax.jms.InvalidDestinationException

javax.jms.InvalidSelectorException

createSharedConsumer

public javax.jms.MessageConsumer createSharedConsumer(javax.jms.Topic topic,
                                             java.lang.String sharedSubscriptionName,
                                             java.lang.String messageSelector)
                                               throws javax.jms.JMSException,
                                                      javax.jms.InvalidDestinationException,
                                                      javax.jms.InvalidSelectorException

Specified by:

createSharedConsumer in interface javax.jms.Session

Throws:

javax.jms.JMSException

javax.jms.InvalidDestinationException

javax.jms.InvalidSelectorException

createSharedDurableConsumer

public javax.jms.MessageConsumer createSharedDurableConsumer(javax.jms.Topic topic,
                                                    java.lang.String sharedSubscriptionName)
                                                      throws javax.jms.JMSException,
                                                             javax.jms.InvalidDestinationException

Specified by:

createSharedDurableConsumer in interface javax.jms.Session

Throws:

javax.jms.JMSException

javax.jms.InvalidDestinationException

createSharedDurableConsumer

public javax.jms.MessageConsumer createSharedDurableConsumer(javax.jms.Topic topic,
                                                    java.lang.String sharedSubscriptionName,
                                                    java.lang.String messageSelector)
                                                      throws javax.jms.InvalidDestinationException,
                                                             javax.jms.IllegalStateException,
                                                             javax.jms.JMSException

Specified by:

createSharedDurableConsumer in interface javax.jms.Session

Throws:

javax.jms.InvalidDestinationException

javax.jms.IllegalStateException

javax.jms.JMSException