javax.jms

Interface QueueBrowser

public interface QueueBrowser

A client uses a QueueBrowser object to look at messages on a queue without removing them.

The getEnumeration method returns a java.util.Enumeration that is used to scan the queue's messages. It may be an enumeration of the entire content of a queue, or it may contain only the messages matching a message selector.

Messages may be arriving and expiring while the scan is done. The JMS API does not require the content of an enumeration to be a static snapshot of queue content. Whether these changes are visible or not depends on the JMS provider.

Note: If browsing a queue with an active consumer, no guarantee is made that the browser will receive all messages published to the queue. The consumer can receive and acknowledge messages before they are delivered to the browser.

Enumeration.hasMoreElements() Returns true if there's at least one message available in the browser's local message buffer. Note: If this method returns false, it does not mean that the queue is empty; subsequent calls to hasMoreElements or Enumeration.nextElement() might return true and a message respectively.

A QueueBrowser can be created from either a Session or a QueueSession.

Since:

4.6 SolOS-TR

Version:

1.1 April 9, 2002

See Also:

Session.createBrowser(javax.jms.Queue), QueueSession.createBrowser(javax.jms.Queue), QueueReceiver

Method Summary

Modifier and Type	Method and Description
void	close() Closes the QueueBrowser.
Enumeration<?>	getEnumeration() Gets an enumeration for browsing the current queue messages in the order they would be received.
String	getMessageSelector() Gets this queue browser's message selector expression.
Queue	getQueue() Gets the queue associated with this queue browser.

Method Detail

getQueue

Queue getQueue()
        throws JMSException

Gets the queue associated with this queue browser.

Returns:

the queue

Throws:

JMSException - if the JMS provider fails to get the queue associated with this browser due to some internal error.

getMessageSelector

String getMessageSelector()
                   throws JMSException

Gets this queue browser's message selector expression.

Returns:

this queue browser's message selector, or null if no message selector exists for the message consumer (that is, if the message selector was not set or was set to null or the empty string)

Throws:

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

getEnumeration

Enumeration<?> getEnumeration()
                       throws JMSException

Gets an enumeration for browsing the current queue messages in the order they would be received.

Enumeration.hasMoreElements() Returns true if there's at least one message available in the browser's local message buffer. Note: If this method returns false, it does not mean that the queue is empty; subsequent calls to hasMoreElements or Enumeration.nextElement() might return true and a message respectively.

Note: A properpty SupportedProperty.SOLACE_JMS_BROWSER_TIMEOUT_IN_MS could be used to specify the maximum time in milliseconds for a QueueBrowser Enumeration.hasMoreElements() to wait for a message to arrive in the browser's local message buffer before returning.

Returns:

an enumeration for browsing the messages

Throws:

JMSException - if the JMS provider fails to get the enumeration for this browser due to some internal error.

JMSException - on error

See Also:

SupportedProperty.SOLACE_JMS_BROWSER_TIMEOUT_IN_MS

close

void close()
    throws JMSException

Closes the QueueBrowser.

Since a provider may allocate some resources on behalf of a QueueBrowser outside the Java virtual machine, clients should close them when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough.

Throws:

JMSException - if the JMS provider fails to close this browser due to some internal error.