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