com.ibm.mq.jms

Class MQQueueBrowser

java.lang.Object

com.ibm.mq.jms.MQRoot

com.ibm.mq.jms.MQQueueBrowser

All Implemented Interfaces:

JmsPropertyContext, JmsQueueBrowser, JmsReadablePropertyContext, java.io.Serializable, java.lang.AutoCloseable, java.util.Map<java.lang.String,java.lang.Object>, javax.jms.QueueBrowser

public class MQQueueBrowser
extends MQRoot
implements javax.jms.QueueBrowser, JmsQueueBrowser

A client uses an MQQueueBrowser to look at messages on a queue without removing them.

Note that the WebSphere MQ extensions class MQQueueEnumeration is used to hold the browse cursor. This means that each instance of this class will have one open handle to the underlying queue on which the MQQueueBrowser is created. These open queues get closed only when the close() method of MQQueueBrowser is called or when the queue does not have any more messages ( either when MQQueueEnumeration.hasMoreElements() returns false, or MQQueueEnumeration.nextElement() throws a NoSuchElementException ).

See Also:

Serialized Form

Nested Class Summary

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

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

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Closes all open queues left in enumerated objects.
java.util.Enumeration<?>	getEnumeration() Gets an enumeration for browsing the current queue messages in the order that they are received.
java.lang.String	getMessageSelector() Gets the queue browser's message selector expression.
javax.jms.Queue	getQueue() Gets an enumeration for browsing the current queue messages in the order that they are received.

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

Method Detail

close

public void close()
           throws javax.jms.JMSException

Closes all open queues left in enumerated objects. Because a provider can allocate some resources outside the JVM on behalf of queue browsers, clients must close them when they are not needed. You cannot rely on garbage collection to reclaim these resources eventually, because this might not occur soon enough.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface javax.jms.QueueBrowser

Throws:

javax.jms.JMSException - if JMS fails to close this browser because of a JMS error.

getEnumeration

public java.util.Enumeration<?> getEnumeration()
                                        throws javax.jms.JMSException

Gets an enumeration for browsing the current queue messages in the order that they are received.

If the queue browser detects a poison message, it will not be returned to the enumeration. What happens to the poison message depends upon the WebSphere MQ messaging provider mode being used by the application:

Applications using WebSphere MQ messaging provider normal mode
--------------------------------------------------------------
If the MQQueueBrowser was created from an XASession that is taking part in a global transaction and the XASession has not previously been used to perform any transactional work, the message will be left on the queue. In all other cases, the WebSphere MQ classes for JMS will move the poison message to the backout requeue queue (as specified by the WebSphere MQ queue parameter BOQNAME) for the queue being browsed.

Applications using WebSphere MQ messaging provider migration mode
-----------------------------------------------------------------
If the MQQueueBrowser was created from an XASession, the message will be left on the queue. In all other cases, the WebSphere MQ classes for JMS will move the poison message to the backout requeue queue (as specified by the WebSphere MQ queue parameter BOQNAME) for the queue being browsed.

Note that if the browser is created for a nonexistent queue, this is not detected until the first call to this method.

Specified by:

getEnumeration in interface javax.jms.QueueBrowser

Returns:

an enumeration for browsing the messages.

Throws:

javax.jms.JMSException - if JMS fails to get the enumeration for this browser because of a JMS error.

getMessageSelector

public java.lang.String getMessageSelector()
                                    throws javax.jms.JMSException

Gets the queue browser's message selector expression.

Specified by:

getMessageSelector in interface javax.jms.QueueBrowser

Returns:

this queue browser's message selector

Throws:

javax.jms.JMSException - if JMS fails to get the message selector for this browser due to some JMS error

getQueue

public javax.jms.Queue getQueue()
                         throws javax.jms.JMSException

Gets an enumeration for browsing the current queue messages in the order that they are received.

Note that if the browser is created for a nonexistent queue, this is not detected until the first call to getEnumeration().

Specified by:

getQueue in interface javax.jms.QueueBrowser

Returns:

an enumeration for browsing the messages.

Throws:

javax.jms.JMSException - if JMS fails to get the enumeration for this browser because of a JMS error.