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