1 /***
2 *
3 * Copyright 2004 Protique Ltd
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 **/
18
19 package org.codehaus.activemq.service;
20
21 import org.codehaus.activemq.broker.BrokerClient;
22 import org.codehaus.activemq.message.ActiveMQDestination;
23 import org.codehaus.activemq.message.ActiveMQMessage;
24 import org.codehaus.activemq.message.ConsumerInfo;
25 import org.codehaus.activemq.message.MessageAck;
26
27 import javax.jms.JMSException;
28
29
30 /***
31 * A Subscription holds messages to be dispatched to a a Client Consumer
32 *
33 * @version $Revision: 1.15 $
34 */
35 public interface Subscription {
36
37
38 /***
39 * Set the active consumer info
40 * @param client
41 *
42 * @param info
43 */
44 public void setActiveConsumer(BrokerClient client,ConsumerInfo info);
45
46 /***
47 * Called when the Subscription is discarded
48 *
49 * @throws JMSException
50 */
51 public void clear() throws JMSException;
52
53 /***
54 * Called when an active message consumer has closed.
55 *
56 * @throws JMSException
57 */
58
59 public void reset() throws JMSException;
60
61 /***
62 * @return Returns the clientId.
63 */
64 public String getClientId();
65
66 /***
67 * @return Returns the subscriberName.
68 */
69 public String getSubscriberName();
70
71 /***
72 * @return Returns the destination.
73 */
74 public ActiveMQDestination getDestination();
75
76 /***
77 * @return Returns the selector.
78 */
79 public String getSelector();
80
81 /***
82 * @return Returns true if an active message consumer is associated with this
83 */
84 public boolean isActive();
85
86 /***
87 * set the state of the Subscription
88 *
89 * @param newActive
90 */
91 public void setActive(boolean newActive) throws JMSException;
92
93 /***
94 * @return Returns the consumerNumber.
95 */
96 public int getConsumerNumber();
97
98 /***
99 * @return the consumer Id for the active consumer
100 */
101 public String getConsumerId();
102
103 /***
104 * determines if the Subscription is interested in the message
105 *
106 * @param message
107 * @return
108 * @throws JMSException
109 */
110 public boolean isTarget(ActiveMQMessage message) throws JMSException;
111
112
113 /***
114 * If the Subscription is a target for the message, the subscription will add a reference to
115 * the message and register an interest in the message to the container
116 *
117 * @param container
118 * @param message
119 * @throws JMSException
120 */
121
122 public void addMessage(MessageContainer container, ActiveMQMessage message) throws JMSException;
123
124 /***
125 * Indicates a message has been delivered to a MessageConsumer
126 * which is typically called for topic based subscriptions
127 *
128 * @param ack
129 * @throws JMSException
130 */
131
132 public void messageConsumed(MessageAck ack) throws JMSException;
133
134 /***
135 * Forces the given message to be redelivered
136 *
137 * @param container
138 * @param ack
139 */
140 public void redeliverMessage(MessageContainer container, MessageAck ack) throws JMSException;
141
142 /***
143 * Retrieve messages to dispatch
144 *
145 * @return
146 * @throws JMSException
147 */
148
149 public ActiveMQMessage[] getMessagesToDispatch() throws JMSException;
150
151 /***
152 * Indicates if this Subscription has more messages to send to the
153 * Consumer
154 *
155 * @return true if more messages available to dispatch
156 * @throws JMSException
157 */
158 public boolean isReadyToDispatch() throws JMSException;
159
160 /***
161 * Indicates the Subscription it's reached it's pre-fetch limit
162 *
163 * @return true/false
164 * @throws JMSException
165 */
166 public boolean isAtPrefetchLimit() throws JMSException;
167
168
169 /***
170 * Indicates the Consumer is a Durable Subscriber
171 *
172 * @return
173 * @throws JMSException
174 */
175 public boolean isDurableTopic() throws JMSException;
176
177 /***
178 * Indicates the consumer is a browser only
179 *
180 * @return true if a Browser
181 * @throws JMSException
182 */
183 public boolean isBrowser() throws JMSException;
184
185
186 /***
187 * Retreives the messageIdentity of the last message sent to this
188 * Queue based Subscription
189 *
190 * @return the messageId of the last message or null
191 * @throws JMSException
192 */
193 public MessageIdentity getLastMessageIdentity() throws JMSException;
194
195
196 /***
197 * Used for a Queue based Subscription to set the last acknowledged
198 * message ID
199 *
200 * @param messageIdentity
201 * @throws JMSException
202 */
203 public void setLastMessageIdentifier(MessageIdentity messageIdentity) throws JMSException;
204
205
206 public boolean isWildcard();
207
208 /***
209 * Returns the persistent key used to uniquely identify this durable topic subscription
210 *
211 * @return
212 */
213 public String getPersistentKey();
214
215 /***
216 * Checks if this subscription is a duplicate durable subscription of the given consumer info
217 *
218 * @param info
219 * @return true if this subscription is a durable topic subscription and the clientID and consumer
220 * names match
221 */
222 public boolean isSameDurableSubscription(ConsumerInfo info) throws JMSException;
223
224 /***
225 * We have not yet committed and so the message acknowledgement has not really occurred yet
226 * but we need to let the dispatcher know that we can commence dispatching more messages
227 * to the client. This is so that we can have a prefetch value of 1 yet we can still consume
228 * 1000 messages inside a transaction, with all the acks coming after the commit() on the client.
229 *
230 * @param ack
231 */
232 public void onAcknowledgeTransactedMessageBeforeCommit(MessageAck ack) throws JMSException;
233
234 /***
235 * Lazily creates the persistent entry representation of this subscription
236 */
237 public SubscriberEntry getSubscriptionEntry();
238 }