1 /*** 2 * Redistribution and use of this software and associated documentation 3 * ("Software"), with or without modification, are permitted provided 4 * that the following conditions are met: 5 * 6 * 1. Redistributions of source code must retain copyright 7 * statements and notices. Redistributions must also contain a 8 * copy of this document. 9 * 10 * 2. Redistributions in binary form must reproduce the 11 * above copyright notice, this list of conditions and the 12 * following disclaimer in the documentation and/or other 13 * materials provided with the distribution. 14 * 15 * 3. The name "Exolab" must not be used to endorse or promote 16 * products derived from this Software without prior written 17 * permission of Exoffice Technologies. For written permission, 18 * please contact info@exolab.org. 19 * 20 * 4. Products derived from this Software may not be called "Exolab" 21 * nor may "Exolab" appear in their names without prior written 22 * permission of Exoffice Technologies. Exolab is a registered 23 * trademark of Exoffice Technologies. 24 * 25 * 5. Due credit should be given to the Exolab Project 26 * (http://www.exolab.org/). 27 * 28 * THIS SOFTWARE IS PROVIDED BY EXOFFICE TECHNOLOGIES AND CONTRIBUTORS 29 * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT 30 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 31 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 32 * EXOFFICE TECHNOLOGIES OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 33 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 34 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 35 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 36 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 37 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 38 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 39 * OF THE POSSIBILITY OF SUCH DAMAGE. 40 * 41 * Copyright 2001-2005 (C) Exoffice Technologies Inc. All Rights Reserved. 42 */ 43 package org.exolab.jms.messagemgr; 44 45 import javax.jms.JMSException; 46 import javax.jms.MessageConsumer; 47 import javax.jms.QueueBrowser; 48 49 import org.exolab.jms.client.JmsDestination; 50 import org.exolab.jms.selector.Selector; 51 import org.exolab.jms.message.MessageImpl; 52 53 54 /*** 55 * <code>ConsumerEndpoint</code> represents the server-side view of of the 56 * {@link MessageConsumer} and {@link QueueBrowser} interfaces 57 * 58 * @author <a href="mailto:jima@comware.com.au">Jim Alateras</a> 59 * @author <a href="mailto:tma@netspace.net.au">Tim Anderson</a> 60 * @version $Revision: 1.3 $ $Date: 2005/08/30 05:30:52 $ 61 */ 62 public interface ConsumerEndpoint 63 extends DestinationCacheEventListener { 64 65 /*** 66 * Returns the identity of this consumer. 67 * 68 * @return the identity of this consumer 69 */ 70 long getId(); 71 72 /*** 73 * Determines if this is a persistent or non-persistent consumer. 74 * <p/> 75 * If persistent, then the consumer is persistent accross subscriptions and 76 * server restarts, and {@link #getPersistentId} returns a non-null value 77 * 78 * @return <code>true</code> if this is a persistent consumer; otherwise 79 * <code>false</code> 80 */ 81 boolean isPersistent(); 82 83 /*** 84 * Returns the persistent identifier for this consumer. This is the identity 85 * of the consumer which is persistent across subscriptions and server 86 * restarts. 87 * 88 * @return the persistent identifier for this consumer, or <code>null</code> 89 * if this is a transient consumer 90 */ 91 String getPersistentId(); 92 93 /*** 94 * Return the destination that this consumer is accessing. 95 * 96 * @return the destination that this consumer is accessing 97 */ 98 JmsDestination getDestination(); 99 100 /*** 101 * Determines if this consumer can consume messages from the specified 102 * destination. 103 * 104 * @param destination the destination 105 * @return <code>true</code> if the consumer can consume messages from 106 * <code>destination</code>; otherwise <code>false</code> 107 */ 108 boolean canConsume(JmsDestination destination); 109 110 /*** 111 * Returns the message selector. 112 * 113 * @return the message selector, or <code>null</code> if none was specified 114 * by the client 115 */ 116 Selector getSelector(); 117 118 /*** 119 * Determines if a message is selected by the consumer. 120 * 121 * @param message the message to check 122 * @return <code>true</code> if the message is selected; otherwise 123 * <code>false</code> 124 */ 125 boolean selects(MessageImpl message); 126 127 /*** 128 * Returns if locally produced messages are being inhibited. 129 * 130 * @return <code>true</code> if locally published messages are being 131 * inhibited. 132 */ 133 boolean getNoLocal(); 134 135 /*** 136 * Return the next available message to the client. 137 * 138 * @param cancel if set, indictates to cancel the receive 139 * @return the next message, or <code>null</code> if none is available 140 * @throws JMSException for any error 141 */ 142 MessageHandle receive(Condition cancel) throws JMSException; 143 144 /*** 145 * Indicates if this is an asynchronous consumer. 146 * <p/> 147 * An asynchronous consumer has a client <code>MessageConsumer</code> with 148 * an associated <code>MessageListener</code>. 149 * 150 * @param asynchronous if <code>true</code> marks this as an asynchronous 151 * consumer 152 */ 153 void setAsynchronous(boolean asynchronous); 154 155 /*** 156 * Determines if this is an asynchronous consumer. 157 * 158 * @return <code>true</code> if this is an asynchronous consumer; otherwise 159 * <code>false</code> 160 */ 161 boolean isAsynchronous(); 162 163 /*** 164 * Indicates that the client is currently waiting for a message. 165 * 166 * @param condition the condition to evaluate to determine if the client is 167 * waiting for message. May be <code>null</code>. 168 */ 169 void setWaitingForMessage(Condition condition); 170 171 /*** 172 * Determines if the client is currently waiting for a message. 173 * 174 * @return <code>true</code> if the client is waiting for messages; 175 * otherwise <code>false</code> 176 */ 177 boolean isWaitingForMessage(); 178 179 /*** 180 * Set the listener for this consumer. If a listener is set, it is notified 181 * when messages become available. 182 * 183 * @param listener the listener to add, or <code>null</code> to remove an 184 * existing listener 185 */ 186 void setListener(ConsumerEndpointListener listener); 187 188 /*** 189 * Returns the number of unsent messages in the cache. 190 * 191 * @return the number of unsent messages 192 */ 193 int getMessageCount(); 194 195 /*** 196 * Determines if this consumer is closed, or in the process of being 197 * closed. 198 * 199 * @return <code>true</code> if this consumer is closed; otherwise 200 * <code>false</code> 201 */ 202 boolean isClosed(); 203 204 /*** 205 * Close and release any resource allocated to this endpoint. 206 */ 207 void close(); 208 209 }