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