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 */
017package org.apache.activemq.store;
018
019import java.io.IOException;
020import java.util.concurrent.Future;
021import org.apache.activemq.Service;
022import org.apache.activemq.broker.ConnectionContext;
023import org.apache.activemq.command.ActiveMQDestination;
024import org.apache.activemq.command.Message;
025import org.apache.activemq.command.MessageAck;
026import org.apache.activemq.command.MessageId;
027import org.apache.activemq.usage.MemoryUsage;
028
029/**
030 * Represents a message store which is used by the persistent implementations
031 * 
032 * 
033 */
034public interface MessageStore extends Service {
035
036    /**
037     * Adds a message to the message store
038     * 
039     * @param context context
040     * @param message
041     * @throws IOException
042     */
043    void addMessage(ConnectionContext context, Message message) throws IOException;
044    
045    /**
046     * Adds a message to the message store
047     * 
048     * @param context context
049     * @param message
050     * @return a Future to track when this is complete
051     * @throws IOException 
052     * @throws IOException
053     */
054    Future<Object> asyncAddQueueMessage(ConnectionContext context, Message message) throws IOException;
055    
056    /**
057     * Adds a message to the message store
058     * 
059     * @param context context
060     * @param message
061     * @return a Future to track when this is complete
062     * @throws IOException 
063     * @throws IOException
064     */
065    Future<Object> asyncAddTopicMessage(ConnectionContext context, Message message) throws IOException;
066
067    /**
068     * Looks up a message using either the String messageID or the
069     * messageNumber. Implementations are encouraged to fill in the missing key
070     * if its easy to do so.
071     * 
072     * @param identity which contains either the messageID or the messageNumber
073     * @return the message or null if it does not exist
074     * @throws IOException
075     */
076    Message getMessage(MessageId identity) throws IOException;
077
078    /**
079     * Removes a message from the message store.
080     * 
081     * @param context
082     * @param ack the ack request that cause the message to be removed. It
083     *                conatins the identity which contains the messageID of the
084     *                message that needs to be removed.
085     * @throws IOException
086     */
087    void removeMessage(ConnectionContext context, MessageAck ack) throws IOException;
088    
089    void removeAsyncMessage(ConnectionContext context, MessageAck ack) throws IOException;
090
091    /**
092     * Removes all the messages from the message store.
093     * 
094     * @param context
095     * @throws IOException
096     */
097    void removeAllMessages(ConnectionContext context) throws IOException;
098
099    /**
100     * Recover any messages to be delivered.
101     * 
102     * @param container
103     * @throws Exception
104     */
105    void recover(MessageRecoveryListener container) throws Exception;
106
107    /**
108     * The destination that the message store is holding messages for.
109     * 
110     * @return the destination
111     */
112    ActiveMQDestination getDestination();
113
114    /**
115     * @param memoeyUSage The SystemUsage that is controlling the
116     *                destination's memory usage.
117     */
118    void setMemoryUsage(MemoryUsage memoeyUSage);
119
120    /**
121     * @return the number of messages ready to deliver
122     * @throws IOException
123     * 
124     */
125    int getMessageCount() throws IOException;
126
127    /**
128     * A hint to the Store to reset any batching state for the Destination
129     * 
130     */
131    void resetBatching();
132
133    void recoverNextMessages(int maxReturned, MessageRecoveryListener listener) throws Exception;
134
135    void dispose(ConnectionContext context);
136
137    /**
138     * allow caching cursors to set the current batch offset when cache is exhausted
139     * @param messageId
140     * @throws Exception 
141     */
142    void setBatch(MessageId messageId) throws Exception;
143    
144    /**
145     * flag to indicate if the store is empty
146     * @return true if the message count is 0
147     * @throws Exception 
148     */
149    boolean isEmpty() throws Exception;
150    
151    /**
152     * A hint to the store to try recover messages according to priority
153     * @param prioritizedMessages
154     */
155    public void setPrioritizedMessages(boolean prioritizedMessages);
156    
157    /**
158     * 
159     * @return true if store is trying to recover messages according to priority
160     */
161    public boolean isPrioritizedMessages();
162    
163}