/**
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.activemq.broker.region.cursors;
import java.io.IOException;
import java.util.LinkedList;
import java.util.List;
import org.apache.activemq.ActiveMQMessageAudit;
import org.apache.activemq.Service;
import org.apache.activemq.broker.ConnectionContext;
import org.apache.activemq.broker.region.Destination;
import org.apache.activemq.broker.region.MessageReference;
import org.apache.activemq.command.MessageId;
import org.apache.activemq.usage.SystemUsage;
/**
* Interface to pending message (messages awaiting disptach to a consumer)
* cursor
*
*
*/
public interface PendingMessageCursor extends Service {
static final long INFINITE_WAIT = 0;
/**
* Add a destination
*
* @param context
* @param destination
* @throws Exception
*/
void add(ConnectionContext context, Destination destination) throws Exception;
/**
* remove a destination
*
* @param context
* @param destination
* @throws Exception
*/
List<MessageReference> remove(ConnectionContext context, Destination destination) throws Exception;
/**
* @return true if there are no pending messages
*/
boolean isEmpty();
/**
* check if a Destination is Empty for this cursor
*
* @param destination
* @return true id the Destination is empty
*/
boolean isEmpty(Destination destination);
/**
* reset the cursor
*/
void reset();
/**
* hint to the cursor to release any locks it might have grabbed after a
* reset
*/
void release();
/**
* add message to await dispatch
*
* @param node
* @return boolean true if successful, false if cursor traps a duplicate
* @throws IOException
* @throws Exception
*/
boolean addMessageLast(MessageReference node) throws Exception;
/**
* add message to await dispatch - if it can
*
* @param node
* @param maxWaitTime
* @return true if successful
* @throws IOException
* @throws Exception
*/
boolean tryAddMessageLast(MessageReference node, long maxWaitTime) throws Exception;
/**
* add message to await dispatch
*
* @param node
* @throws Exception
*/
void addMessageFirst(MessageReference node) throws Exception;
/**
* Add a message recovered from a retroactive policy
*
* @param node
* @throws Exception
*/
void addRecoveredMessage(MessageReference node) throws Exception;
/**
* @return true if there pending messages to dispatch
*/
boolean hasNext();
/**
* @return the next pending message with its reference count increment
*/
MessageReference next();
/**
* remove the message at the cursor position
*/
void remove();
/**
* @return the number of pending messages
*/
int size();
long messageSize();
/**
* clear all pending messages
*/
void clear();
/**
* Informs the Broker if the subscription needs to intervention to recover
* it's state e.g. DurableTopicSubscriber may do
*
* @return true if recovery required
*/
boolean isRecoveryRequired();
/**
* @return the maximum batch size
*/
int getMaxBatchSize();
/**
* Set the max batch size
*
* @param maxBatchSize
*/
void setMaxBatchSize(int maxBatchSize);
/**
* Give the cursor a hint that we are about to remove messages from memory
* only
*/
void resetForGC();
/**
* remove a node
*
* @param node
*/
void remove(MessageReference node);
/**
* free up any internal buffers
*/
void gc();
/**
* Set the UsageManager
*
* @param systemUsage
* @see org.apache.activemq.usage.SystemUsage
*/
void setSystemUsage(SystemUsage systemUsage);
/**
* @return the usageManager
*/
SystemUsage getSystemUsage();
/**
* @return the memoryUsageHighWaterMark
*/
int getMemoryUsageHighWaterMark();
/**
* @param memoryUsageHighWaterMark the memoryUsageHighWaterMark to set
*/
void setMemoryUsageHighWaterMark(int memoryUsageHighWaterMark);
/**
* @return true if the cursor is full
*/
boolean isFull();
/**
* @return true if the cursor has space to page messages into
*/
public boolean hasSpace();
/**
* @return true if the cursor has buffered messages ready to deliver
*/
boolean hasMessagesBufferedToDeliver();
/**
* destroy the cursor
*
* @throws Exception
*/
void destroy() throws Exception;
/**
* Page in a restricted number of messages and increment the reference count
*
* @param maxItems
* @return a list of paged in messages
*/
LinkedList<MessageReference> pageInList(int maxItems);
/**
* set the maximum number of producers to track at one time
* @param value
*/
void setMaxProducersToAudit(int value);
/**
* @return the maximum number of producers to audit
*/
int getMaxProducersToAudit();
/**
* Set the maximum depth of message ids to track
* @param depth
*/
void setMaxAuditDepth(int depth);
/**
* @return the audit depth
*/
int getMaxAuditDepth();
/**
* @return the enableAudit
*/
public boolean isEnableAudit();
/**
* @param enableAudit the enableAudit to set
*/
public void setEnableAudit(boolean enableAudit);
/**
* @return true if the underlying state of this cursor
* disappears when the broker shuts down
*/
public boolean isTransient();
/**
* set the audit
* @param audit
*/
public void setMessageAudit(ActiveMQMessageAudit audit);
/**
* @return the audit - could be null
*/
public ActiveMQMessageAudit getMessageAudit();
/**
* use a cache to improve performance
* @param useCache
*/
public void setUseCache(boolean useCache);
/**
* @return true if a cache may be used
*/
public boolean isUseCache();
/**
* remove from auditing the message id
* @param id
*/
public void rollback(MessageId id);
/**
* @return true if cache is being used
*/
public boolean isCacheEnabled();
public void rebase();
}