View Javadoc

1   /*** 
2    * 
3    * Copyright 2004 Protique Ltd
4    * 
5    * Licensed under the Apache License, Version 2.0 (the "License"); 
6    * you may not use this file except in compliance with the License. 
7    * You may obtain a copy of the License at 
8    * 
9    * http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS, 
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
14   * See the License for the specific language governing permissions and 
15   * limitations under the License. 
16   * 
17   **/
18  
19  package org.codehaus.activemq.service;
20  
21  import org.codehaus.activemq.broker.BrokerClient;
22  import org.codehaus.activemq.message.ActiveMQDestination;
23  import org.codehaus.activemq.message.ActiveMQMessage;
24  import org.codehaus.activemq.message.ConsumerInfo;
25  import org.codehaus.activemq.message.MessageAck;
26  
27  import javax.jms.JMSException;
28  
29  
30  /***
31   * A Subscription holds messages to be dispatched to a a Client Consumer
32   *
33   * @version $Revision: 1.15 $
34   */
35  public interface Subscription {
36  
37  
38      /***
39       * Set the active consumer info
40       * @param client
41       *
42       * @param info
43       */
44      public void setActiveConsumer(BrokerClient client,ConsumerInfo info);
45  
46      /***
47       * Called when the Subscription is discarded
48       *
49       * @throws JMSException
50       */
51      public void clear() throws JMSException;
52  
53      /***
54       * Called when an active message consumer has closed.
55       *
56       * @throws JMSException
57       */
58  
59      public void reset() throws JMSException;
60  
61      /***
62       * @return Returns the clientId.
63       */
64      public String getClientId();
65  
66      /***
67       * @return Returns the subscriberName.
68       */
69      public String getSubscriberName();
70  
71      /***
72       * @return Returns the destination.
73       */
74      public ActiveMQDestination getDestination();
75  
76      /***
77       * @return Returns the selector.
78       */
79      public String getSelector();
80  
81      /***
82       * @return Returns true if an active message consumer is associated with this
83       */
84      public boolean isActive();
85  
86      /***
87       * set the state of the Subscription
88       *
89       * @param newActive
90       */
91      public void setActive(boolean newActive) throws JMSException;
92  
93      /***
94       * @return Returns the consumerNumber.
95       */
96      public int getConsumerNumber();
97  
98      /***
99       * @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      * Forces the given message to be redelivered
136      *
137      * @param container
138      * @param ack
139      */
140     public void redeliverMessage(MessageContainer container, MessageAck ack) throws JMSException;
141 
142     /***
143      * Retrieve messages to dispatch
144      *
145      * @return
146      * @throws JMSException
147      */
148 
149     public ActiveMQMessage[] getMessagesToDispatch() throws JMSException;
150 
151     /***
152      * Indicates if this Subscription has more messages to send to the
153      * Consumer
154      *
155      * @return true if more messages available to dispatch
156      * @throws JMSException
157      */
158     public boolean isReadyToDispatch() throws JMSException;
159 
160     /***
161      * Indicates the Subscription it's reached it's pre-fetch limit
162      *
163      * @return true/false
164      * @throws JMSException
165      */
166     public boolean isAtPrefetchLimit() throws JMSException;
167 
168 
169     /***
170      * Indicates the Consumer is a Durable Subscriber
171      *
172      * @return
173      * @throws JMSException
174      */
175     public boolean isDurableTopic() throws JMSException;
176 
177     /***
178      * Indicates the consumer is a browser only
179      *
180      * @return true if a Browser
181      * @throws JMSException
182      */
183     public boolean isBrowser() throws JMSException;
184 
185 
186     /***
187      * Retreives the messageIdentity of the last message sent to this
188      * Queue based Subscription
189      *
190      * @return the messageId of the last message or null
191      * @throws JMSException
192      */
193     public MessageIdentity getLastMessageIdentity() throws JMSException;
194 
195 
196     /***
197      * Used for a Queue based Subscription to set the last acknowledged
198      * message ID
199      *
200      * @param messageIdentity
201      * @throws JMSException
202      */
203     public void setLastMessageIdentifier(MessageIdentity messageIdentity) throws JMSException;
204 
205 
206     public boolean isWildcard();
207 
208     /***
209      * Returns the persistent key used to uniquely identify this durable topic subscription
210      *
211      * @return
212      */
213     public String getPersistentKey();
214 
215     /***
216      * Checks if this subscription is a duplicate durable subscription of the given consumer info
217      *
218      * @param info
219      * @return true if this subscription is a durable topic subscription and the clientID and consumer
220      *         names match
221      */
222     public boolean isSameDurableSubscription(ConsumerInfo info) throws JMSException;
223 
224     /***
225      * We have not yet committed and so the message acknowledgement has not really occurred yet
226      * but we need to let the dispatcher know that we can commence dispatching more messages
227      * to the client. This is so that we can have a prefetch value of 1 yet we can still consume
228      * 1000 messages inside a transaction, with all the acks coming after the commit() on the client.
229      *
230      * @param ack
231      */
232     public void onAcknowledgeTransactedMessageBeforeCommit(MessageAck ack) throws JMSException;
233 
234     /***
235      * Lazily creates the persistent entry representation of this subscription
236      */
237     public SubscriberEntry getSubscriptionEntry();
238 }