1. /*

  2.  * Copyright 2002 Sun Microsystems, Inc. All rights reserved.

  3.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  4.  */

  5. 

  6. package javax.jms;

  7. 

  8. import java.util.Enumeration;

  9. 

  10. /** A client uses a <CODE>QueueBrowser</CODE> object to look at messages on a 

  11.   * queue without removing them.

  12.   *

  13.   * <P>The <CODE>getEnumeration</CODE> method returns a 

  14.   * <CODE>java.util.Enumeration</CODE> that is used to scan 

  15.   * the queue's messages. It may be an enumeration of the entire content of a 

  16.   * queue, or it may contain only the messages matching a message selector.

  17.   *

  18.   * <P>Messages may be arriving and expiring while the scan is done. The JMS API

  19.   * does 

  20.   * not require the content of an enumeration to be a static snapshot of queue 

  21.   * content. Whether these changes are visible or not depends on the JMS 

  22.   * provider.

  23.   *

  24.   * @version     1.0 - 13 August 1998

  25.   * @author      Mark Hapner

  26.   * @author      Rich Burridge

  27.   *

  28.   * @see         javax.jms.QueueSession#createBrowser(Queue)

  29.   * @see         javax.jms.QueueSession#createBrowser(Queue, String)

  30.   * @see         javax.jms.QueueReceiver

  31.   */

  32. 

  33. public interface QueueBrowser {

  34. 

  35.     /** Gets the queue associated with this queue browser.

  36.       * 

  37.       * @return the queue

  38.       *  

  39.       * @exception JMSException if the JMS provider fails to get the

  40.       *                         queue associated with this browser

  41.       *                         due to some internal error.

  42.       */

  43. 

  44.     Queue 

  45.     getQueue() throws JMSException;

  46. 

  47. 

  48.     /** Gets this queue browser's message selector expression.

  49.       *  

  50.       * @return this queue browser's message selector, or null if no

  51.       *         message selector exists for the message consumer (that is, if 

  52.       *         the message selector was not set or was set to null or the 

  53.       *         empty string)

  54.       *

  55.       * @exception JMSException if the JMS provider fails to get the

  56.       *                         message selector for this browser

  57.       *                         due to some internal error.

  58.       */

  59. 

  60.     String

  61.     getMessageSelector() throws JMSException;

  62. 

  63. 

  64.     /** Gets an enumeration for browsing the current queue messages in the

  65.       * order they would be received.

  66.       *

  67.       * @return an enumeration for browsing the messages

  68.       *  

  69.       * @exception JMSException if the JMS provider fails to get the

  70.       *                         enumeration for this browser

  71.       *                         due to some internal error.

  72.       */

  73. 

  74.     Enumeration 

  75.     getEnumeration() throws JMSException;

  76. 

  77. 

  78.     /** Closes the <CODE>QueueBrowser</CODE>.

  79.       *

  80.       * <P>Since a provider may allocate some resources on behalf of a 

  81.       * QueueBrowser outside the Java virtual machine, clients should close them

  82.       * when they 

  83.       * are not needed. Relying on garbage collection to eventually reclaim 

  84.       * these resources may not be timely enough.

  85.       *

  86.       * @exception JMSException if the JMS provider fails to close this

  87.       *                         browser due to some internal error.

  88.       */

  89. 

  90.     void 

  91.     close() throws JMSException;

  92. }