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.MessageAck;
025import org.apache.activemq.command.MessageId;
026import org.apache.activemq.command.SubscriptionInfo;
027
028/**
029 * A MessageStore for durable topic subscriptions
030 */
031public interface TopicMessageStore extends MessageStore {
032
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 ack
042     *
043     * @throws IOException
044     */
045    void acknowledge(ConnectionContext context, String clientId, String subscriptionName, MessageId messageId, MessageAck ack) throws IOException;
046
047    /**
048     * @param clientId
049     * @param subscriptionName
050     *
051     * @throws IOException
052     * @throws JMSException
053     */
054    void deleteSubscription(String clientId, String subscriptionName) throws IOException;
055
056    /**
057     * For the new subscription find the last acknowledged message ID and then
058     * find any new messages since then and dispatch them to the subscription.
059     * <p/> e.g. if we dispatched some messages to a new durable topic
060     * subscriber, then went down before acknowledging any messages, we need to
061     * know the correct point from which to recover from.
062     *
063     * @param clientId
064     * @param subscriptionName
065     * @param listener
066     *
067     * @throws Exception
068     */
069    void recoverSubscription(String clientId, String subscriptionName, MessageRecoveryListener listener) throws Exception;
070
071    /**
072     * For an active subscription - retrieve messages from the store for the
073     * subscriber after the lastMessageId messageId <p/>
074     *
075     * @param clientId
076     * @param subscriptionName
077     * @param maxReturned
078     * @param listener
079     *
080     * @throws Exception
081     */
082    void recoverNextMessages(String clientId, String subscriptionName, int maxReturned, MessageRecoveryListener listener) throws Exception;
083
084    /**
085     * A hint to the Store to reset any batching state for a durable subscriber
086     *
087     * @param clientId
088     * @param subscriptionName
089     */
090    void resetBatching(String clientId, String subscriptionName);
091
092    /**
093     * Get the number of messages ready to deliver from the store to a durable
094     * subscriber
095     *
096     * @param clientId
097     * @param subscriberName
098     *
099     * @return the outstanding message count
100     *
101     * @throws IOException
102     */
103    int getMessageCount(String clientId, String subscriberName) throws IOException;
104
105    /**
106     * Get the total size of the messages ready to deliver from the store to the
107     * durable subscriber
108     *
109     * @param clientId
110     * @param subscriberName
111     * @return
112     * @throws IOException
113     */
114    long getMessageSize(String clientId, String subscriberName) throws IOException;
115
116    /**
117     * The subscription metrics contained in this store
118     *
119     * @return
120     */
121    MessageStoreSubscriptionStatistics getMessageStoreSubStatistics();
122
123    /**
124     * Finds the subscriber entry for the given consumer info
125     *
126     * @param clientId
127     * @param subscriptionName
128     *
129     * @return the SubscriptionInfo
130     *
131     * @throws IOException
132     */
133    SubscriptionInfo lookupSubscription(String clientId, String subscriptionName) throws IOException;
134
135    /**
136     * Lists all the durable subscriptions for a given destination.
137     *
138     * @return an array SubscriptionInfos
139     * @throws IOException
140     */
141    SubscriptionInfo[] getAllSubscriptions() throws IOException;
142
143    /**
144     * Inserts the subscriber info due to a subscription change <p/> If this is
145     * a new subscription and the retroactive is false, then the last message
146     * sent to the topic should be set as the last message acknowledged by they
147     * new subscription. Otherwise, if retroactive is true, then create the
148     * subscription without it having an acknowledged message so that on
149     * recovery, all message recorded for the topic get replayed.
150     *
151     * @param subscriptionInfo
152     * @param retroactive
153     *
154     * @throws IOException
155     */
156    void addSubscription(SubscriptionInfo subscriptionInfo, boolean retroactive) throws IOException;
157}