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 2005 (C) Exoffice Technologies Inc. All Rights Reserved.
42 *
43 * $Id: ConsumerManager.java,v 1.4 2005/11/12 12:42:54 tanderson Exp $
44 */
45 package org.exolab.jms.messagemgr;
46
47 import javax.jms.InvalidDestinationException;
48 import javax.jms.InvalidSelectorException;
49 import javax.jms.JMSException;
50
51 import org.exolab.jms.client.JmsDestination;
52 import org.exolab.jms.client.JmsQueue;
53 import org.exolab.jms.client.JmsTopic;
54
55
56 /***
57 * <code>ConsumerManager</code> is responsible for creating and managing the
58 * lifecycle of consumers.
59 *
60 * @author <a href="mailto:tma@netspace.net.au">Tim Anderson</a>
61 * @version $Revision: 1.4 $ $Date: 2005/11/12 12:42:54 $
62 */
63 public interface ConsumerManager {
64
65 /***
66 * Create a new durable subscription.
67 * <p/>
68 * A client can change an existing durable subscription by creating a new
69 * subscription with the same name and a new topic. Changing a durable
70 * subscriber is equivalent to unsubscribing the old one and creating a new
71 * one.
72 *
73 * @param topic the topic to subscribe to
74 * @param name the subscription name
75 * @param clientID the client identifier. May be <code>null</code>
76 * @throws InvalidDestinationException if <code>topic</code> is not a
77 * persistent destination, or
78 * <code>name</code> is an invalid
79 * subscription name
80 * @throws JMSException if the durable consumer can't be
81 * created
82 */
83 void subscribe(JmsTopic topic, String name, String clientID)
84 throws JMSException;
85
86 /***
87 * Remove a durable subscription.
88 * <p/>
89 * A subscription may only be removed if the associated {@link
90 * DurableConsumerEndpoint} is inactive.
91 *
92 * @param name the subscription name
93 * @param clientID the client identifier. May be <code>null</code>
94 * @throws InvalidDestinationException if an invalid subscription name is
95 * specified.
96 * @throws JMSException if the durable consumer is active, or
97 * cannot be removed
98 */
99 void unsubscribe(String name, String clientID) throws JMSException;
100
101 /***
102 * Remove all durable subscriptions for a destination.
103 * <p/>
104 * Subscriptions may only be removed if the associated {@link
105 * ConsumerEndpoint}s are inactive.
106 *
107 * @param topic the topic to remove consumers for
108 * @throws JMSException if the subscriptions can't be removed
109 */
110 void unsubscribe(JmsTopic topic) throws JMSException;
111
112 /***
113 * Create a transient consumer for the specified destination.
114 *
115 * @param destination the destination to consume messages from
116 * @param connectionId the identity of the connection that owns this
117 * consumer
118 * @param selector the message selector. May be <code>null</code>
119 * @param noLocal if true, and the destination is a topic, inhibits the
120 * delivery of messages published by its own connection.
121 * The behavior for <code>noLocal</code> is not
122 * specified if the destination is a queue.
123 * @return a new transient consumer
124 * @throws InvalidSelectorException if the selector is not well formed
125 * @throws JMSException if the consumer can't be created
126 */
127 ConsumerEndpoint createConsumer(JmsDestination destination,
128 long connectionId, String selector,
129 boolean noLocal)
130 throws JMSException;
131
132 /***
133 * Create a durable consumer.
134 *
135 * @param topic the topic to subscribe to
136 * @param name the subscription name
137 * @param clientID the client identifier. May be <code>null</code>.
138 * @param connectionId the identity of the connection that owns this
139 * consumer
140 * @param noLocal if true, and the destination is a topic, inhibits the
141 * delivery of messages published by its own
142 * connection.
143 * @param selector the message selector. May be <code>null</code>
144 * @return the durable consumer endpoint
145 * @throws InvalidDestinationException if <code>topic</code> is not a
146 * persistent destination
147 * @throws InvalidSelectorException if the selector is not well formed
148 * @throws JMSException if a durable consumer is already
149 * active with the same <code>name</code>
150 */
151 DurableConsumerEndpoint createDurableConsumer(JmsTopic topic, String name,
152 String clientID,
153 long connectionId,
154 boolean noLocal,
155 String selector)
156 throws JMSException;
157
158 /***
159 * Create a new queue browser.
160 *
161 * @param queue the queue to browse
162 * @param selector the message selector. May be <code>null</code>
163 * @return the queue browser endpoint
164 * @throws InvalidSelectorException if the selector is not well formed
165 * @throws JMSException if the browser can't be created
166 */
167 ConsumerEndpoint createQueueBrowser(JmsQueue queue, String selector)
168 throws JMSException;
169
170 /***
171 * Close a consumer.
172 *
173 * @param consumer the consumer to close
174 */
175 void closeConsumer(ConsumerEndpoint consumer);
176
177 /***
178 * Return the consumer with the specified identity.
179 *
180 * @param consumerId the identity of the consumer
181 * @return the associated consumer, or <code>null</code> if none exists
182 */
183 ConsumerEndpoint getConsumerEndpoint(long consumerId);
184
185 /***
186 * Return the consumer with the specified persistent identity.
187 *
188 * @param persistentId the persistent identity of the consumer
189 * @return the associated consumer, or <code>null</code> if none exists
190 */
191 ConsumerEndpoint getConsumerEndpoint(String persistentId);
192
193 /***
194 * Determines if there are any active consumers for a destination.
195 *
196 * @param destination the destination
197 * @return <code>true</code> if there is at least one consumer
198 */
199 boolean hasActiveConsumers(JmsDestination destination);
200
201 }