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    import javax.jms.JMSException;
021    import org.apache.activemq.broker.ConnectionContext;
022    import org.apache.activemq.command.MessageAck;
023    import org.apache.activemq.command.MessageId;
024    import org.apache.activemq.command.SubscriptionInfo;
025    
026    /**
027     * A MessageStore for durable topic subscriptions
028     * 
029     * 
030     */
031    public 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 addSubsciption(SubscriptionInfo subscriptionInfo, boolean retroactive) throws IOException;
133    }