1   /*
    2    * JBoss, Home of Professional Open Source
    3    * Copyright 2005, JBoss Inc., and individual contributors as indicated
    4    * by the @authors tag. See the copyright.txt in the distribution for a
    5    * full listing of individual contributors.
    6    *
    7    * This is free software; you can redistribute it and/or modify it
    8    * under the terms of the GNU Lesser General Public License as
    9    * published by the Free Software Foundation; either version 2.1 of
   10    * the License, or (at your option) any later version.
   11    *
   12    * This software is distributed in the hope that it will be useful,
   13    * but WITHOUT ANY WARRANTY; without even the implied warranty of
   14    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   15    * Lesser General Public License for more details.
   16    *
   17    * You should have received a copy of the GNU Lesser General Public
   18    * License along with this software; if not, write to the Free
   19    * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
   20    * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
   21    */
   22   package javax.jms;
   23   
   24   /** A client uses a <CODE>QueueReceiver</CODE> object to receive messages that 
   25    * have been delivered to a queue.
   26    *
   27    * <P>Although it is possible to have multiple <CODE>QueueReceiver</CODE>s 
   28    * for the same queue, the JMS API does not define how messages are 
   29    * distributed between the <CODE>QueueReceiver</CODE>s.
   30    *
   31    * <P>If a <CODE>QueueReceiver</CODE> specifies a message selector, the 
   32    * messages that are not selected remain on the queue. By definition, a message
   33    * selector allows a <CODE>QueueReceiver</CODE> to skip messages. This 
   34    * means that when the skipped messages are eventually read, the total ordering
   35    * of the reads does not retain the partial order defined by each message 
   36    * producer. Only <CODE>QueueReceiver</CODE>s without a message selector
   37    * will read messages in message producer order.
   38    *
   39    * <P>Creating a <CODE>MessageConsumer</CODE> provides the same features as
   40    * creating a <CODE>QueueReceiver</CODE>. A <CODE>MessageConsumer</CODE> object is 
   41    * recommended for creating new code. The  <CODE>QueueReceiver</CODE> is
   42    * provided to support existing code.
   43    *
   44    * @see         javax.jms.Session#createConsumer(Destination, String)
   45    * @see         javax.jms.Session#createConsumer(Destination)
   46    * @see         javax.jms.QueueSession#createReceiver(Queue, String)
   47    * @see         javax.jms.QueueSession#createReceiver(Queue)
   48    * @see         javax.jms.MessageConsumer
   49    */
   50   
   51   public interface QueueReceiver extends MessageConsumer
   52   {
   53   
   54      /** Gets the <CODE>Queue</CODE> associated with this queue receiver.
   55       *  
   56       * @return this receiver's <CODE>Queue</CODE> 
   57       *  
   58       * @exception JMSException if the JMS provider fails to get the queue for
   59       *                         this queue receiver
   60       *                         due to some internal error.
   61       */
   62   
   63      Queue getQueue() throws JMSException;
   64   }