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