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: /** A client uses a <CODE>MessageConsumer</CODE> object to receive messages
025: * from a destination. A <CODE>MessageConsumer</CODE> object is created by
026: * passing a <CODE>Destination</CODE> object to a message-consumer creation
027: * method supplied by a session.
028: *
029: * <P><CODE>MessageConsumer</CODE> is the parent interface for all message
030: * consumers.
031: *
032: * <P>A message consumer can be created with a message selector. A message
033: * selector allows
034: * the client to restrict the messages delivered to the message consumer to
035: * those that match the selector.
036: *
037: * <P>A client may either synchronously receive a message consumer's messages
038: * or have the consumer asynchronously deliver them as they arrive.
039: *
040: * <P>For synchronous receipt, a client can request the next message from a
041: * message consumer using one of its <CODE>receive</CODE> methods. There are
042: * several variations of <CODE>receive</CODE> that allow a
043: * client to poll or wait for the next message.
044: *
045: * <P>For asynchronous delivery, a client can register a
046: * <CODE>MessageListener</CODE> object with a message consumer.
047: * As messages arrive at the message consumer, it delivers them by calling the
048: * <CODE>MessageListener</CODE>'s <CODE>onMessage</CODE> method.
049: *
050: * <P>It is a client programming error for a <CODE>MessageListener</CODE> to
051: * throw an exception.
052: *
053: * @see javax.jms.QueueReceiver
054: * @see javax.jms.TopicSubscriber
055: * @see javax.jms.Session
056: */
057:
058: public interface MessageConsumer {
059:
060: /** Gets this message consumer's message selector expression.
061: *
062: * @return this message consumer's message selector, or null if no
063: * message selector exists for the message consumer (that is, if
064: * the message selector was not set or was set to null or the
065: * empty string)
066: *
067: * @exception JMSException if the JMS provider fails to get the message
068: * selector due to some internal error.
069: */
070:
071: String getMessageSelector() throws JMSException;
072:
073: /** Gets the message consumer's <CODE>MessageListener</CODE>.
074: *
075: * @return the listener for the message consumer, or null if no listener
076: * is set
077: *
078: * @exception JMSException if the JMS provider fails to get the message
079: * listener due to some internal error.
080: * @see javax.jms.MessageConsumer#setMessageListener
081: */
082:
083: MessageListener getMessageListener() throws JMSException;
084:
085: /** Sets the message consumer's <CODE>MessageListener</CODE>.
086: *
087: * <P>Setting the message listener to null is the equivalent of
088: * unsetting the message listener for the message consumer.
089: *
090: * <P>The effect of calling <CODE>MessageConsumer.setMessageListener</CODE>
091: * while messages are being consumed by an existing listener
092: * or the consumer is being used to consume messages synchronously
093: * is undefined.
094: *
095: * @param listener the listener to which the messages are to be
096: * delivered
097: *
098: * @exception JMSException if the JMS provider fails to set the message
099: * listener due to some internal error.
100: * @see javax.jms.MessageConsumer#getMessageListener
101: */
102:
103: void setMessageListener(MessageListener listener)
104: throws JMSException;
105:
106: /** Receives the next message produced for this message consumer.
107: *
108: * <P>This call blocks indefinitely until a message is produced
109: * or until this message consumer is closed.
110: *
111: * <P>If this <CODE>receive</CODE> is done within a transaction, the
112: * consumer retains the message until the transaction commits.
113: *
114: * @return the next message produced for this message consumer, or
115: * null if this message consumer is concurrently closed
116: *
117: * @exception JMSException if the JMS provider fails to receive the next
118: * message due to some internal error.
119: *
120: */
121:
122: Message receive() throws JMSException;
123:
124: /** Receives the next message that arrives within the specified
125: * timeout interval.
126: *
127: * <P>This call blocks until a message arrives, the
128: * timeout expires, or this message consumer is closed.
129: * A <CODE>timeout</CODE> of zero never expires, and the call blocks
130: * indefinitely.
131: *
132: * @param timeout the timeout value (in milliseconds)
133: *
134: * @return the next message produced for this message consumer, or
135: * null if the timeout expires or this message consumer is concurrently
136: * closed
137: *
138: * @exception JMSException if the JMS provider fails to receive the next
139: * message due to some internal error.
140: */
141:
142: Message receive(long timeout) throws JMSException;
143:
144: /** Receives the next message if one is immediately available.
145: *
146: * @return the next message produced for this message consumer, or
147: * null if one is not available
148: *
149: * @exception JMSException if the JMS provider fails to receive the next
150: * message due to some internal error.
151: */
152:
153: Message receiveNoWait() throws JMSException;
154:
155: /** Closes the message consumer.
156: *
157: * <P>Since a provider may allocate some resources on behalf of a
158: * <CODE>MessageConsumer</CODE> outside the Java virtual machine, clients
159: * should close them when they
160: * are not needed. Relying on garbage collection to eventually reclaim
161: * these resources may not be timely enough.
162: *
163: * <P>This call blocks until a <CODE>receive</CODE> or message listener in
164: * progress has completed. A blocked message consumer <CODE>receive</CODE>
165: * call
166: * returns null when this message consumer is closed.
167: *
168: * @exception JMSException if the JMS provider fails to close the consumer
169: * due to some internal error.
170: */
171:
172: void close() throws JMSException;
173: }
|