MessageConsumer


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  package javax.jms;
25  
26  /** A client uses a <CODE>MessageConsumer</CODE> object to receive messages 
27    * from a destination.  A <CODE>MessageConsumer</CODE> object is created by 
28    * passing a <CODE>Destination</CODE> object to a message-consumer creation
29    * method supplied by a session.
30    *
31    * <P><CODE>MessageConsumer</CODE> is the parent interface for all message 
32    * consumers.
33    *
34    * <P>A message consumer can be created with a message selector. A message
35    * selector allows 
36    * the client to restrict the messages delivered to the message consumer to 
37    * those that match the selector.
38    *
39    * <P>A client may either synchronously receive a message consumer's messages 
40    * or have the consumer asynchronously deliver them as they arrive.
41    *
42    * <P>For synchronous receipt, a client can request the next message from a 
43    * message consumer using one of its <CODE>receive</CODE> methods. There are 
44    * several variations of <CODE>receive</CODE> that allow a 
45    * client to poll or wait for the next message.
46    *
47    * <P>For asynchronous delivery, a client can register a 
48    * <CODE>MessageListener</CODE> object with a message consumer. 
49    * As messages arrive at the message consumer, it delivers them by calling the 
50    * <CODE>MessageListener</CODE>'s <CODE>onMessage</CODE> method.
51    *
52    * <P>It is a client programming error for a <CODE>MessageListener</CODE> to 
53    * throw an exception.
54    *
55    * @version     1.0 - 13 March 1998
56    * @author      Mark Hapner
57    * @author      Rich Burridge
58    *
59    * @see         javax.jms.QueueReceiver
60    * @see         javax.jms.TopicSubscriber
61    * @see         javax.jms.Session
62    */
63  
64  public interface MessageConsumer {
65  
66      /** Gets this message consumer's message selector expression.
67        *  
68        * @return this message consumer's message selector, or null if no
69        *         message selector exists for the message consumer (that is, if 
70        *         the message selector was not set or was set to null or the 
71        *         empty string)
72        *  
73        * @exception JMSException if the JMS provider fails to get the message
74        *                         selector due to some internal error.
75        */ 
76  
77      String  
78      getMessageSelector() throws JMSException  ;
79  
80  
81      /** Gets the message consumer's <CODE>MessageListener</CODE>.
82        *  
83        * @return the listener for the message consumer, or null if no listener
84        * is set
85        *  
86        * @exception JMSException if the JMS provider fails to get the message
87        *                         listener due to some internal error.
88        * @see javax.jms.MessageConsumer#setMessageListener
89        */ 
90  
91      MessageListener  
92      getMessageListener() throws JMSException  ;
93  
94  
95      /** Sets the message consumer's <CODE>MessageListener</CODE>.
96        * 
97        * <P>Setting the message listener to null is the equivalent of 
98        * unsetting the message listener for the message consumer.
99        *
100       * <P>The effect of calling <CODE>MessageConsumer.setMessageListener</CODE>
101       * while messages are being consumed by an existing listener
102       * or the consumer is being used to consume messages synchronously
103       * is undefined.
104       *  
105       * @param listener the listener to which the messages are to be 
106       *                 delivered
107       *  
108       * @exception JMSException if the JMS provider fails to set the message
109       *                         listener due to some internal error.
110       * @see javax.jms.MessageConsumer#getMessageListener
111       */ 
112 
113     void
114     setMessageListener(MessageListener   listener) throws JMSException  ;
115 
116 
117     /** Receives the next message produced for this message consumer.
118       *  
119       * <P>This call blocks indefinitely until a message is produced
120       * or until this message consumer is closed.
121       *
122       * <P>If this <CODE>receive</CODE> is done within a transaction, the 
123       * consumer retains the message until the transaction commits.
124       *  
125       * @return the next message produced for this message consumer, or 
126       * null if this message consumer is concurrently closed
127       *  
128       * @exception JMSException if the JMS provider fails to receive the next
129       *                         message due to some internal error.
130       * 
131       */ 
132  
133     Message  
134     receive() throws JMSException  ;
135 
136 
137     /** Receives the next message that arrives within the specified
138       * timeout interval.
139       *  
140       * <P>This call blocks until a message arrives, the
141       * timeout expires, or this message consumer is closed.
142       * A <CODE>timeout</CODE> of zero never expires, and the call blocks 
143       * indefinitely.
144       *
145       * @param timeout the timeout value (in milliseconds)
146       *
147       * @return the next message produced for this message consumer, or 
148       * null if the timeout expires or this message consumer is concurrently 
149       * closed
150       *
151       * @exception JMSException if the JMS provider fails to receive the next
152       *                         message due to some internal error.
153       */ 
154 
155     Message  
156     receive(long timeout) throws JMSException  ;
157 
158 
159     /** Receives the next message if one is immediately available.
160       *
161       * @return the next message produced for this message consumer, or 
162       * null if one is not available
163       *  
164       * @exception JMSException if the JMS provider fails to receive the next
165       *                         message due to some internal error.
166       */ 
167 
168     Message  
169     receiveNoWait() throws JMSException  ;
170 
171 
172     /** Closes the message consumer.
173       *
174       * <P>Since a provider may allocate some resources on behalf of a
175       * <CODE>MessageConsumer</CODE> outside the Java virtual machine, clients 
176       * should close them when they
177       * are not needed. Relying on garbage collection to eventually reclaim
178       * these resources may not be timely enough.
179       *
180       * <P>This call blocks until a <CODE>receive</CODE> or message listener in 
181       * progress has completed. A blocked message consumer <CODE>receive</CODE> 
182       * call 
183       * returns null when this message consumer is closed.
184       *  
185       * @exception JMSException if the JMS provider fails to close the consumer
186       *                         due to some internal error.
187       */ 
188 
189     void
190     close() throws JMSException  ;
191 }
192
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags