1 /**
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. 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 package org.apache.activemq.broker.region.cursors;
18
19 import java.io.IOException;
20 import java.util.LinkedList;
21 import java.util.List;
22 import org.apache.activemq.ActiveMQMessageAudit;
23 import org.apache.activemq.Service;
24 import org.apache.activemq.broker.ConnectionContext;
25 import org.apache.activemq.broker.region.Destination;
26 import org.apache.activemq.broker.region.MessageReference;
27 import org.apache.activemq.command.MessageId;
28 import org.apache.activemq.usage.SystemUsage;
29
30 /**
31 * Interface to pending message (messages awaiting disptach to a consumer)
32 * cursor
33 *
34 * @version $Revision: 915914 $
35 */
36 public interface PendingMessageCursor extends Service {
37
38 /**
39 * Add a destination
40 *
41 * @param context
42 * @param destination
43 * @throws Exception
44 */
45 void add(ConnectionContext context, Destination destination) throws Exception;
46
47 /**
48 * remove a destination
49 *
50 * @param context
51 * @param destination
52 * @throws Exception
53 */
54 List<MessageReference> remove(ConnectionContext context, Destination destination) throws Exception;
55
56 /**
57 * @return true if there are no pending messages
58 */
59 boolean isEmpty();
60
61 /**
62 * check if a Destination is Empty for this cursor
63 *
64 * @param destination
65 * @return true id the Destination is empty
66 */
67 boolean isEmpty(Destination destination);
68
69 /**
70 * reset the cursor
71 */
72 void reset();
73
74 /**
75 * hint to the cursor to release any locks it might have grabbed after a
76 * reset
77 */
78 void release();
79
80 /**
81 * add message to await dispatch
82 *
83 * @param node
84 * @throws IOException
85 * @throws Exception
86 */
87 void addMessageLast(MessageReference node) throws Exception;
88
89 /**
90 * add message to await dispatch
91 *
92 * @param node
93 * @throws Exception
94 */
95 void addMessageFirst(MessageReference node) throws Exception;
96
97 /**
98 * Add a message recovered from a retroactive policy
99 *
100 * @param node
101 * @throws Exception
102 */
103 void addRecoveredMessage(MessageReference node) throws Exception;
104
105 /**
106 * @return true if there pending messages to dispatch
107 */
108 boolean hasNext();
109
110 /**
111 * @return the next pending message with its reference count increment
112 */
113 MessageReference next();
114
115 /**
116 * remove the message at the cursor position
117 */
118 void remove();
119
120 /**
121 * @return the number of pending messages
122 */
123 int size();
124
125 /**
126 * clear all pending messages
127 */
128 void clear();
129
130 /**
131 * Informs the Broker if the subscription needs to intervention to recover
132 * it's state e.g. DurableTopicSubscriber may do
133 *
134 * @return true if recovery required
135 */
136 boolean isRecoveryRequired();
137
138 /**
139 * @return the maximum batch size
140 */
141 int getMaxBatchSize();
142
143 /**
144 * Set the max batch size
145 *
146 * @param maxBatchSize
147 */
148 void setMaxBatchSize(int maxBatchSize);
149
150 /**
151 * Give the cursor a hint that we are about to remove messages from memory
152 * only
153 */
154 void resetForGC();
155
156 /**
157 * remove a node
158 *
159 * @param node
160 */
161 void remove(MessageReference node);
162
163 /**
164 * free up any internal buffers
165 */
166 void gc();
167
168 /**
169 * Set the UsageManager
170 *
171 * @param systemUsage
172 * @see org.apache.activemq.usage.SystemUsage
173 */
174 void setSystemUsage(SystemUsage systemUsage);
175
176 /**
177 * @return the usageManager
178 */
179 SystemUsage getSystemUsage();
180
181 /**
182 * @return the memoryUsageHighWaterMark
183 */
184 int getMemoryUsageHighWaterMark();
185
186 /**
187 * @param memoryUsageHighWaterMark the memoryUsageHighWaterMark to set
188 */
189 void setMemoryUsageHighWaterMark(int memoryUsageHighWaterMark);
190
191 /**
192 * @return true if the cursor is full
193 */
194 boolean isFull();
195
196 /**
197 * @return true if the cursor has space to page messages into
198 */
199 public boolean hasSpace();
200
201 /**
202 * @return true if the cursor has buffered messages ready to deliver
203 */
204 boolean hasMessagesBufferedToDeliver();
205
206 /**
207 * destroy the cursor
208 *
209 * @throws Exception
210 */
211 void destroy() throws Exception;
212
213 /**
214 * Page in a restricted number of messages and increment the reference count
215 *
216 * @param maxItems
217 * @return a list of paged in messages
218 */
219 LinkedList<MessageReference> pageInList(int maxItems);
220
221 /**
222 * set the maximum number of producers to track at one time
223 * @param value
224 */
225 void setMaxProducersToAudit(int value);
226
227 /**
228 * @return the maximum number of producers to audit
229 */
230 int getMaxProducersToAudit();
231
232 /**
233 * Set the maximum depth of message ids to track
234 * @param depth
235 */
236 void setMaxAuditDepth(int depth);
237
238 /**
239 * @return the audit depth
240 */
241 int getMaxAuditDepth();
242
243 /**
244 * @return the enableAudit
245 */
246 public boolean isEnableAudit();
247 /**
248 * @param enableAudit the enableAudit to set
249 */
250 public void setEnableAudit(boolean enableAudit);
251
252 /**
253 * @return true if the underlying state of this cursor
254 * disappears when the broker shuts down
255 */
256 public boolean isTransient();
257
258
259 /**
260 * set the audit
261 * @param audit
262 */
263 public void setMessageAudit(ActiveMQMessageAudit audit);
264
265
266 /**
267 * @return the audit - could be null
268 */
269 public ActiveMQMessageAudit getMessageAudit();
270
271 /**
272 * use a cache to improve performance
273 * @param useCache
274 */
275 public void setUseCache(boolean useCache);
276
277 /**
278 * @return true if a cache is being used
279 */
280 public boolean isUseCache();
281
282 /**
283 * remove from auditing the message id
284 * @param id
285 */
286 public void rollback(MessageId id);
287
288 }