001    /** 
002     * 
003     * Copyright 2004 Protique Ltd
004     * 
005     * Licensed under the Apache License, Version 2.0 (the "License"); 
006     * you may not use this file except in compliance with the License. 
007     * 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     **/
018    
019    package org.activemq.service;
020    
021    import org.activemq.broker.BrokerClient;
022    import org.activemq.message.ActiveMQDestination;
023    import org.activemq.message.ActiveMQMessage;
024    import org.activemq.message.ConsumerInfo;
025    import org.activemq.message.MessageAck;
026    
027    import javax.jms.JMSException;
028    
029    
030    /**
031     * A Subscription holds messages to be dispatched to a a Client Consumer
032     *
033     * @version $Revision: 1.1.1.1 $
034     */
035    public interface Subscription {
036    
037    
038        /**
039         * Set the active consumer info
040         * @param client
041         *
042         * @param info
043         */
044        public void setActiveConsumer(BrokerClient client,ConsumerInfo info);
045    
046        /**
047         * Called when the Subscription is discarded
048         *
049         * @throws JMSException
050         */
051        public void clear() throws JMSException;
052    
053        /**
054         * Called when an active message consumer has closed.
055         *
056         * @throws JMSException
057         */
058    
059        public void reset() throws JMSException;
060    
061        /**
062         * @return Returns the clientId.
063         */
064        public String getClientId();
065    
066        /**
067         * @return Returns the subscriberName.
068         */
069        public String getSubscriberName();
070    
071        /**
072         * @return Returns the destination.
073         */
074        public ActiveMQDestination getDestination();
075    
076        /**
077         * @return Returns the selector.
078         */
079        public String getSelector();
080    
081        /**
082         * @return Returns true if an active message consumer is associated with this
083         */
084        public boolean isActive();
085    
086        /**
087         * set the state of the Subscription
088         *
089         * @param newActive
090         */
091        public void setActive(boolean newActive) throws JMSException;
092    
093        /**
094         * @return Returns the consumerNumber.
095         */
096        public int getConsumerNumber();
097    
098        /**
099         * @return the consumer Id for the active consumer
100         */
101        public String getConsumerId();
102    
103        /**
104         * determines if the Subscription is interested in the message
105         *
106         * @param message
107         * @return
108         * @throws JMSException
109         */
110        public boolean isTarget(ActiveMQMessage message) throws JMSException;
111    
112    
113        /**
114         * If the Subscription is a target for the message, the subscription will add a reference to
115         * the message and register an interest in the message to the container
116         *
117         * @param container
118         * @param message
119         * @throws JMSException
120         */
121    
122        public void addMessage(MessageContainer container, ActiveMQMessage message) throws JMSException;
123    
124        /**
125         * Indicates a message has been delivered to a MessageConsumer
126         * which is typically called for topic based subscriptions
127         *
128         * @param ack
129         * @throws JMSException
130         */
131    
132        public void messageConsumed(MessageAck ack) throws JMSException;
133    
134        /**
135         * Retrieve messages to dispatch
136         *
137         * @return
138         * @throws JMSException
139         */
140    
141        public ActiveMQMessage[] getMessagesToDispatch() throws JMSException;
142    
143        /**
144         * Indicates if this Subscription has more messages to send to the
145         * Consumer
146         *
147         * @return true if more messages available to dispatch
148         * @throws JMSException
149         */
150        public boolean isReadyToDispatch() throws JMSException;
151    
152        /**
153         * Indicates the Subscription it's reached it's pre-fetch limit
154         *
155         * @return true/false
156         * @throws JMSException
157         */
158        public boolean isAtPrefetchLimit() throws JMSException;
159    
160    
161        /**
162         * Indicates the Consumer is a Durable Subscriber
163         *
164         * @return
165         * @throws JMSException
166         */
167        public boolean isDurableTopic() throws JMSException;
168    
169        /**
170         * Indicates the consumer is a browser only
171         *
172         * @return true if a Browser
173         * @throws JMSException
174         */
175        public boolean isBrowser() throws JMSException;
176    
177    
178        /**
179         * Retreives the messageIdentity of the last message sent to this
180         * Queue based Subscription
181         *
182         * @return the messageId of the last message or null
183         * @throws JMSException
184         */
185        public MessageIdentity getLastMessageIdentity() throws JMSException;
186    
187    
188        /**
189         * Used for a Queue based Subscription to set the last acknowledged
190         * message ID
191         *
192         * @param messageIdentity
193         * @throws JMSException
194         */
195        public void setLastMessageIdentifier(MessageIdentity messageIdentity) throws JMSException;
196    
197    
198        public boolean isWildcard();
199    
200        /**
201         * Returns the persistent key used to uniquely identify this durable topic subscription
202         *
203         * @return
204         */
205        public String getPersistentKey();
206    
207        /**
208         * Checks if this subscription is a duplicate durable subscription of the given consumer info
209         *
210         * @param info
211         * @return true if this subscription is a durable topic subscription and the clientID and consumer
212         *         names match
213         */
214        public boolean isSameDurableSubscription(ConsumerInfo info) throws JMSException;
215    
216        /**
217         * Lazily creates the persistent entry representation of this subscription
218         */
219        public SubscriberEntry getSubscriptionEntry();
220    
221        public boolean isLocalSubscription();
222    }