001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package javax.jms;
023:
024: import java.util.Enumeration;
025:
026: /** A client uses a <CODE>QueueBrowser</CODE> object to look at messages on a
027: * queue without removing them.
028: *
029: * <P>The <CODE>getEnumeration</CODE> method returns a
030: * <CODE>java.util.Enumeration</CODE> that is used to scan
031: * the queue's messages. It may be an enumeration of the entire content of a
032: * queue, or it may contain only the messages matching a message selector.
033: *
034: * <P>Messages may be arriving and expiring while the scan is done. The JMS API
035: * does
036: * not require the content of an enumeration to be a static snapshot of queue
037: * content. Whether these changes are visible or not depends on the JMS
038: * provider.
039: *
040: *<P>A <CODE>QueueBrowser</CODE> can be created from either a
041: * <CODE>Session</CODE> or a <CODE> QueueSession</CODE>.
042: *
043: * @see javax.jms.Session#createBrowser
044: * @see javax.jms.QueueSession#createBrowser
045: * @see javax.jms.QueueReceiver
046: */
047:
048: public interface QueueBrowser {
049:
050: /** Gets the queue associated with this queue browser.
051: *
052: * @return the queue
053: *
054: * @exception JMSException if the JMS provider fails to get the
055: * queue associated with this browser
056: * due to some internal error.
057: */
058:
059: Queue getQueue() throws JMSException;
060:
061: /** Gets this queue browser's message selector expression.
062: *
063: * @return this queue browser's message selector, or null if no
064: * message selector exists for the message consumer (that is, if
065: * the message selector was not set or was set to null or the
066: * empty string)
067: *
068: * @exception JMSException if the JMS provider fails to get the
069: * message selector for this browser
070: * due to some internal error.
071: */
072:
073: String getMessageSelector() throws JMSException;
074:
075: /** Gets an enumeration for browsing the current queue messages in the
076: * order they would be received.
077: *
078: * @return an enumeration for browsing the messages
079: *
080: * @exception JMSException if the JMS provider fails to get the
081: * enumeration for this browser
082: * due to some internal error.
083: */
084:
085: Enumeration getEnumeration() throws JMSException;
086:
087: /** Closes the <CODE>QueueBrowser</CODE>.
088: *
089: * <P>Since a provider may allocate some resources on behalf of a
090: * QueueBrowser outside the Java virtual machine, clients should close them
091: * when they
092: * are not needed. Relying on garbage collection to eventually reclaim
093: * these resources may not be timely enough.
094: *
095: * @exception JMSException if the JMS provider fails to close this
096: * browser due to some internal error.
097: */
098:
099: void close() throws JMSException;
100: }
|