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 }