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.message.ActiveMQDestination;
22  import org.codehaus.activemq.message.ActiveMQMessage;
23  import org.codehaus.activemq.message.ConsumerInfo;
24  import org.codehaus.activemq.message.MessageAck;
25  
26  import javax.jms.JMSException;
27  
28  
29  /***
30   * A Subscription holds messages to be dispatched to a a Client Consumer
31   *
32   * @version $Revision: 1.13 $
33   */
34  public interface Subscription {
35  
36  
37      /***
38       * Set the active consumer info
39       *
40       * @param info
41       */
42      public void setActiveConsumer(ConsumerInfo info);
43  
44      /***
45       * Called when the Subscription is discarded
46       *
47       * @throws JMSException
48       */
49      public void clear() throws JMSException;
50  
51      /***
52       * Called when an active message consumer has closed.
53       *
54       * @throws JMSException
55       */
56  
57      public void reset() throws JMSException;
58  
59      /***
60       * @return Returns the clientId.
61       */
62      public String getClientId();
63  
64      /***
65       * @return Returns the subscriberName.
66       */
67      public String getSubscriberName();
68  
69      /***
70       * @return Returns the destination.
71       */
72      public ActiveMQDestination getDestination();
73  
74      /***
75       * @return Returns the selector.
76       */
77      public String getSelector();
78  
79      /***
80       * @return Returns true if an active message consumer is associated with this
81       */
82      public boolean isActive();
83  
84      /***
85       * set the state of the Subscription
86       *
87       * @param newActive
88       */
89      public void setActive(boolean newActive) throws JMSException;
90  
91      /***
92       * @return Returns the consumerNumber.
93       */
94      public int getConsumerNumber();
95  
96      /***
97       * @return the consumer Id for the active consumer
98       */
99      public String getConsumerId();
100 
101     /***
102      * determines if the Subscription is interested in the message
103      *
104      * @param message
105      * @return
106      * @throws JMSException
107      */
108     public boolean isTarget(ActiveMQMessage message) throws JMSException;
109 
110 
111     /***
112      * If the Subscription is a target for the message, the subscription will add a reference to
113      * the message and register an interest in the message to the container
114      *
115      * @param container
116      * @param message
117      * @throws JMSException
118      */
119 
120     public void addMessage(MessageContainer container, ActiveMQMessage message) throws JMSException;
121 
122     /***
123      * Indicates a message has been delivered to a MessageConsumer
124      * which is typically called for topic based subscriptions
125      *
126      * @param ack
127      * @throws JMSException
128      */
129 
130     public void messageConsumed(MessageAck ack) throws JMSException;
131 
132     /***
133      * Forces the given message to be redelivered
134      *
135      * @param container
136      * @param ack
137      */
138     public void redeliverMessage(MessageContainer container, MessageAck ack) throws JMSException;
139 
140     /***
141      * Retrieve messages to dispatch
142      *
143      * @return
144      * @throws JMSException
145      */
146 
147     public ActiveMQMessage[] getMessagesToDispatch() throws JMSException;
148 
149     /***
150      * Indicates if this Subscription has more messages to send to the
151      * Consumer
152      *
153      * @return true if more messages available to dispatch
154      * @throws JMSException
155      */
156     public boolean isReadyToDispatch() throws JMSException;
157 
158     /***
159      * Indicates the Subscription it's reached it's pre-fetch limit
160      *
161      * @return true/false
162      * @throws JMSException
163      */
164     public boolean isAtPrefetchLimit() throws JMSException;
165 
166 
167     /***
168      * Indicates the Consumer is a Durable Subscriber
169      *
170      * @return
171      * @throws JMSException
172      */
173     public boolean isDurableTopic() throws JMSException;
174 
175     /***
176      * Indicates the consumer is a browser only
177      *
178      * @return true if a Browser
179      * @throws JMSException
180      */
181     public boolean isBrowser() throws JMSException;
182 
183 
184     /***
185      * Retreives the messageIdentity of the last message sent to this
186      * Queue based Subscription
187      *
188      * @return the messageId of the last message or null
189      * @throws JMSException
190      */
191     public MessageIdentity getLastMessageIdentity() throws JMSException;
192 
193 
194     /***
195      * Used for a Queue based Subscription to set the last acknowledged
196      * message ID
197      *
198      * @param messageIdentity
199      * @throws JMSException
200      */
201     public void setLastMessageIdentifier(MessageIdentity messageIdentity) throws JMSException;
202 
203 
204     public boolean isWildcard();
205 
206     /***
207      * Returns the persistent key used to uniquely identify this durable topic subscription
208      *
209      * @return
210      */
211     public String getPersistentKey();
212 
213     /***
214      * Checks if this subscription is a duplicate durable subscription of the given consumer info
215      *
216      * @param info
217      * @return true if this subscription is a durable topic subscription and the clientID and consumer
218      *         names match
219      */
220     public boolean isSameDurableSubscription(ConsumerInfo info) throws JMSException;
221 
222     /***
223      * We have not yet committed and so the message acknowledgement has not really occurred yet
224      * but we need to let the dispatcher know that we can commence dispatching more messages
225      * to the client. This is so that we can have a prefetch value of 1 yet we can still consume
226      * 1000 messages inside a transaction, with all the acks coming after the commit() on the client.
227      *
228      * @param ack
229      */
230     public void onAcknowledgeTransactedMessageBeforeCommit(MessageAck ack) throws JMSException;
231 }