001    /**
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.activemq.broker.region.cursors;
018    
019    import java.io.IOException;
020    import java.util.LinkedList;
021    import java.util.List;
022    import org.apache.activemq.ActiveMQMessageAudit;
023    import org.apache.activemq.Service;
024    import org.apache.activemq.broker.ConnectionContext;
025    import org.apache.activemq.broker.region.Destination;
026    import org.apache.activemq.broker.region.MessageReference;
027    import org.apache.activemq.command.MessageId;
028    import org.apache.activemq.usage.SystemUsage;
029    
030    /**
031     * Interface to pending message (messages awaiting disptach to a consumer)
032     * cursor
033     * 
034     * @version $Revision: 915914 $
035     */
036    public interface PendingMessageCursor extends Service {
037    
038        /**
039         * Add a destination
040         * 
041         * @param context
042         * @param destination
043         * @throws Exception
044         */
045        void add(ConnectionContext context, Destination destination) throws Exception;
046    
047        /**
048         * remove a destination
049         * 
050         * @param context
051         * @param destination
052         * @throws Exception
053         */
054        List<MessageReference> remove(ConnectionContext context, Destination destination) throws Exception;
055    
056        /**
057         * @return true if there are no pending messages
058         */
059        boolean isEmpty();
060    
061        /**
062         * check if a Destination is Empty for this cursor
063         * 
064         * @param destination
065         * @return true id the Destination is empty
066         */
067        boolean isEmpty(Destination destination);
068    
069        /**
070         * reset the cursor
071         */
072        void reset();
073    
074        /**
075         * hint to the cursor to release any locks it might have grabbed after a
076         * reset
077         */
078        void release();
079    
080        /**
081         * add message to await dispatch
082         * 
083         * @param node
084         * @throws IOException
085         * @throws Exception
086         */
087        void addMessageLast(MessageReference node) throws Exception;
088    
089        /**
090         * add message to await dispatch
091         * 
092         * @param node
093         * @throws Exception
094         */
095        void addMessageFirst(MessageReference node) throws Exception;
096    
097        /**
098         * Add a message recovered from a retroactive policy
099         * 
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    }