01: /*
02: * @(#)QueueBrowser.java 1.20 02/04/09
03: *
04: * Copyright 1997-2002 Sun Microsystems, Inc. All Rights Reserved.
05: *
06: * SUN PROPRIETARY/CONFIDENTIAL.
07: * This software is the proprietary information of Sun Microsystems, Inc.
08: * Use is subject to license terms.
09: *
10: */
11:
12: package javax.jms;
13:
14: import java.util.Enumeration;
15:
16: /** A client uses a <CODE>QueueBrowser</CODE> object to look at messages on a
17: * queue without removing them.
18: *
19: * <P>The <CODE>getEnumeration</CODE> method returns a
20: * <CODE>java.util.Enumeration</CODE> that is used to scan
21: * the queue's messages. It may be an enumeration of the entire content of a
22: * queue, or it may contain only the messages matching a message selector.
23: *
24: * <P>Messages may be arriving and expiring while the scan is done. The JMS API
25: * does
26: * not require the content of an enumeration to be a static snapshot of queue
27: * content. Whether these changes are visible or not depends on the JMS
28: * provider.
29: *
30: *<P>A <CODE>QueueBrowser</CODE> can be created from either a
31: * <CODE>Session</CODE> or a <CODE> QueueSession</CODE>.
32: *
33: * @version 1.1 April 9, 2002
34: * @author Mark Hapner
35: * @author Rich Burridge
36: * @author Kate Stout
37: *
38: * @see javax.jms.Session#createBrowser
39: * @see javax.jms.QueueSession#createBrowser
40: * @see javax.jms.QueueReceiver
41: */
42:
43: public interface QueueBrowser {
44:
45: /** Gets the queue associated with this queue browser.
46: *
47: * @return the queue
48: *
49: * @exception JMSException if the JMS provider fails to get the
50: * queue associated with this browser
51: * due to some internal error.
52: */
53:
54: Queue getQueue() throws JMSException;
55:
56: /** Gets this queue browser's message selector expression.
57: *
58: * @return this queue browser's message selector, or null if no
59: * message selector exists for the message consumer (that is, if
60: * the message selector was not set or was set to null or the
61: * empty string)
62: *
63: * @exception JMSException if the JMS provider fails to get the
64: * message selector for this browser
65: * due to some internal error.
66: */
67:
68: String getMessageSelector() throws JMSException;
69:
70: /** Gets an enumeration for browsing the current queue messages in the
71: * order they would be received.
72: *
73: * @return an enumeration for browsing the messages
74: *
75: * @exception JMSException if the JMS provider fails to get the
76: * enumeration for this browser
77: * due to some internal error.
78: */
79:
80: Enumeration getEnumeration() throws JMSException;
81:
82: /** Closes the <CODE>QueueBrowser</CODE>.
83: *
84: * <P>Since a provider may allocate some resources on behalf of a
85: * QueueBrowser outside the Java virtual machine, clients should close them
86: * when they
87: * are not needed. Relying on garbage collection to eventually reclaim
88: * these resources may not be timely enough.
89: *
90: * @exception JMSException if the JMS provider fails to close this
91: * browser due to some internal error.
92: */
93:
94: void close() throws JMSException;
95: }
|