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 javax.jms.JMSException;
021import org.apache.activemq.broker.ConnectionContext;
022import org.apache.activemq.command.MessageAck;
023import org.apache.activemq.command.MessageId;
024import org.apache.activemq.command.SubscriptionInfo;
025
026/**
027 * A MessageStore for durable topic subscriptions
028 * 
029 * 
030 */
031public interface TopicMessageStore extends MessageStore {
032    /**
033     * Stores the last acknowledged messgeID for the given subscription so that
034     * we can recover and commence dispatching messages from the last checkpoint
035     * 
036     * @param context
037     * @param clientId
038     * @param subscriptionName
039     * @param messageId
040     * @param subscriptionPersistentId
041     * @throws IOException
042     */
043    void acknowledge(ConnectionContext context, String clientId, String subscriptionName, MessageId messageId, MessageAck ack) throws IOException;
044    
045    /**
046     * @param clientId
047     * @param subscriptionName
048     * @param sub
049     * @throws IOException
050     * @throws JMSException
051     */
052    void deleteSubscription(String clientId, String subscriptionName) throws IOException;
053
054    /**
055     * For the new subscription find the last acknowledged message ID and then
056     * find any new messages since then and dispatch them to the subscription.
057     * <p/> e.g. if we dispatched some messages to a new durable topic
058     * subscriber, then went down before acknowledging any messages, we need to
059     * know the correct point from which to recover from.
060     * 
061     * @param clientId
062     * @param subscriptionName
063     * @param listener
064     * @param subscription
065     * @throws Exception
066     */
067    void recoverSubscription(String clientId, String subscriptionName, MessageRecoveryListener listener) throws Exception;
068
069    /**
070     * For an active subscription - retrieve messages from the store for the
071     * subscriber after the lastMessageId messageId <p/>
072     * 
073     * @param clientId
074     * @param subscriptionName
075     * @param maxReturned
076     * @param listener
077     * @throws Exception
078     */
079    void recoverNextMessages(String clientId, String subscriptionName, int maxReturned, MessageRecoveryListener listener) throws Exception;
080
081    /**
082     * A hint to the Store to reset any batching state for a durable subscriber
083     * 
084     * @param clientId
085     * @param subscriptionName
086     */
087    void resetBatching(String clientId, String subscriptionName);
088
089    /**
090     * Get the number of messages ready to deliver from the store to a durable
091     * subscriber
092     * 
093     * @param clientId
094     * @param subscriberName
095     * @return the outstanding message count
096     * @throws IOException
097     */
098    int getMessageCount(String clientId, String subscriberName) throws IOException;
099
100    /**
101     * Finds the subscriber entry for the given consumer info
102     * 
103     * @param clientId
104     * @param subscriptionName
105     * @return the SubscriptionInfo
106     * @throws IOException
107     */
108    SubscriptionInfo lookupSubscription(String clientId, String subscriptionName) throws IOException;
109
110    /**
111     * Lists all the durable subscriptions for a given destination.
112     * 
113     * @return an array SubscriptionInfos
114     * @throws IOException
115     */
116    SubscriptionInfo[] getAllSubscriptions() throws IOException;
117
118    /**
119     * Inserts the subscriber info due to a subscription change <p/> If this is
120     * a new subscription and the retroactive is false, then the last message
121     * sent to the topic should be set as the last message acknowledged by they
122     * new subscription. Otherwise, if retroactive is true, then create the
123     * subscription without it having an acknowledged message so that on
124     * recovery, all message recorded for the topic get replayed.
125     * 
126     * @param clientId
127     * @param subscriptionName
128     * @param selector
129     * @param retroactive
130     * @throws IOException
131     */
132    void addSubscription(SubscriptionInfo subscriptionInfo, boolean retroactive) throws IOException;
133}