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