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     */
017    package org.apache.activemq.store;
018    
019    import java.io.IOException;
020    
021    import javax.jms.JMSException;
022    
023    import org.apache.activemq.broker.ConnectionContext;
024    import org.apache.activemq.command.MessageId;
025    import org.apache.activemq.command.SubscriptionInfo;
026    
027    /**
028     * A MessageStore for durable topic subscriptions
029     * 
030     * 
031     */
032    public 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    }