01: /*
02: * @(#)QueueReceiver.java 1.21 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: /** A client uses a <CODE>QueueReceiver</CODE> object to receive messages that
15: * have been delivered to a queue.
16: *
17: * <P>Although it is possible to have multiple <CODE>QueueReceiver</CODE>s
18: * for the same queue, the JMS API does not define how messages are
19: * distributed between the <CODE>QueueReceiver</CODE>s.
20: *
21: * <P>If a <CODE>QueueReceiver</CODE> specifies a message selector, the
22: * messages that are not selected remain on the queue. By definition, a message
23: * selector allows a <CODE>QueueReceiver</CODE> to skip messages. This
24: * means that when the skipped messages are eventually read, the total ordering
25: * of the reads does not retain the partial order defined by each message
26: * producer. Only <CODE>QueueReceiver</CODE>s without a message selector
27: * will read messages in message producer order.
28: *
29: * <P>Creating a <CODE>MessageConsumer</CODE> provides the same features as
30: * creating a <CODE>QueueReceiver</CODE>. A <CODE>MessageConsumer</CODE> object is
31: * recommended for creating new code. The <CODE>QueueReceiver</CODE> is
32: * provided to support existing code.
33: *
34: * @version 1.1 February 2, 2002
35: * @author Mark Hapner
36: * @author Rich Burridge
37: * @author Kate Stout
38: *
39: * @see javax.jms.Session#createConsumer(Destination, String)
40: * @see javax.jms.Session#createConsumer(Destination)
41: * @see javax.jms.QueueSession#createReceiver(Queue, String)
42: * @see javax.jms.QueueSession#createReceiver(Queue)
43: * @see javax.jms.MessageConsumer
44: */
45:
46: public interface QueueReceiver extends MessageConsumer {
47:
48: /** Gets the <CODE>Queue</CODE> associated with this queue receiver.
49: *
50: * @return this receiver's <CODE>Queue</CODE>
51: *
52: * @exception JMSException if the JMS provider fails to get the queue for
53: * this queue receiver
54: * due to some internal error.
55: */
56:
57: Queue getQueue() throws JMSException;
58: }
|