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