javax.jms

## Interface QueueBrowser

- All Superinterfaces:
    AutoCloseable

      public interface QueueBrowser
      extends AutoCloseable

  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.

  A message must not be returned by a `QueueBrowser` before its delivery time has been reached.

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

  Since:
    JMS 1.0
  See Also:
    `Session.createBrowser(javax.jms.Queue)`, `QueueSession.createBrowser(javax.jms.Queue)`, `QueueReceiver`

- - ### Method Summary

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

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

      Specified by:
        `close` in interface `AutoCloseable`
      Throws:
        `JMSException` - if the JMS provider fails to close this browser due to some internal error.

Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.