001    /*
002     * Copyright 2009 Red Hat, Inc.
003     * Red Hat licenses this file to you under the Apache License, version
004     * 2.0 (the "License"); you may not use this file except in compliance
005     * with the License.  You may obtain a copy of the License at
006     *    http://www.apache.org/licenses/LICENSE-2.0
007     * Unless required by applicable law or agreed to in writing, software
008     * distributed under the License is distributed on an "AS IS" BASIS,
009     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
010     * implied.  See the License for the specific language governing
011     * permissions and limitations under the License.
012     */
013    
014    package org.hornetq.api.core.client;
015    
016    import java.util.List;
017    
018    import javax.transaction.xa.XAResource;
019    
020    import org.hornetq.api.core.HornetQException;
021    import org.hornetq.api.core.SimpleString;
022    
023    /**
024     * A ClientSession is a single-thread object required for producing and consuming messages.
025     *
026     * @author <a href="mailto:tim.fox@jboss.com">Tim Fox</a>
027     * @author <a href="mailto:clebert.suconic@jboss.org">Clebert Suconic</a>
028     * @author <a href="mailto:ataylor@redhat.com">Andy Taylor</a>
029     * @author <a href="mailto:jmesnil@redhat.com">Jeff Mesnil</a>
030     *
031     */
032    public interface ClientSession extends XAResource
033    {
034       /**
035        * Information returned by a binding query
036        *
037        * @see ClientSession#bindingQuery(SimpleString)
038        */
039       public interface BindingQuery
040       {
041          /**
042           * Returns <code>true</code> if the binding exists, <code>false</code> else.
043           */
044          boolean isExists();
045    
046          /**
047           * Returns the names of the queues bound to the binding.
048           */
049          public List<SimpleString> getQueueNames();
050       }
051    
052       /**
053        * Information returned by a queue query
054        *
055        * @see ClientSession#queueQuery(SimpleString)
056        */
057       public interface QueueQuery
058       {
059          /**
060           * Returns <code>true</code> if the queue exists, <code>false</code> else.
061           */
062          boolean isExists();
063    
064          /**
065           * Returns <code>true</code> if the queue is durable, <code>false</code> else.
066           */
067          boolean isDurable();
068    
069          /**
070           * Returns the number of consumers attached to the queue.
071           */
072          int getConsumerCount();
073    
074          /**
075           * Returns the number of messages in the queue.
076           */
077          long getMessageCount();
078    
079          /**
080           * Returns the queue's filter string (or <code>null</code> if the queue has no filter).
081           */
082          SimpleString getFilterString();
083    
084          /**
085           * Returns the address that the queue is bound to.
086           */
087          SimpleString getAddress();
088       }
089    
090       // Lifecycle operations ------------------------------------------
091    
092       /**
093        * Starts the session.
094        * The session must be started before ClientConsumers created by the session can consume messages from the queue.
095        *
096        * @throws HornetQException if an exception occurs while starting the session
097        */
098       void start() throws HornetQException;
099    
100       /**
101        * Stops the session.
102        * ClientConsumers created by the session can not consume messages when the session is stopped.
103        *
104        * @throws HornetQException if an exception occurs while stopping the session
105        */
106       void stop() throws HornetQException;
107    
108       /**
109        * Closes the session.
110        *
111        * @throws HornetQException if an exception occurs while closing the session
112        */
113       void close() throws HornetQException;
114    
115       /**
116        * Returns whether the session is closed or not.
117        *
118        * @return <code>true</code> if the session is closed, <code>false</code> else
119        */
120       boolean isClosed();
121    
122       /**
123        * Adds a FailureListener to the session which is notified if a failure occurs on the session.
124        *
125        * @param listener the listener to add
126        */
127       void addFailureListener(SessionFailureListener listener);
128    
129       /**
130        * Removes a FailureListener to the session.
131        *
132        * @param listener the listener to remove
133        * @return <code>true</code> if the listener was removed, <code>false</code> else
134        */
135       boolean removeFailureListener(SessionFailureListener listener);
136    
137       /**
138        * Returns the server's incrementingVersion.
139        *
140        * @return the server's <code>incrementingVersion</code>
141        */
142       int getVersion();
143    
144       // Queue Operations ----------------------------------------------
145    
146       /**
147        * Creates a <em>non-temporary</em> queue.
148        *
149        * @param address the queue will be bound to this address
150        * @param queueName the name of the queue
151        * @param durable whether the queue is durable or not
152        * @throws HornetQException in an exception occurs while creating the queue
153        */
154       void createQueue(SimpleString address, SimpleString queueName, boolean durable) throws HornetQException;
155    
156       /**
157        * Creates a <em>non-temporary</em> queue.
158        *
159        * @param address the queue will be bound to this address
160        * @param queueName the name of the queue
161        * @param durable whether the queue is durable or not
162        * @throws HornetQException in an exception occurs while creating the queue
163        */
164       void createQueue(String address, String queueName, boolean durable) throws HornetQException;
165    
166       /**
167        * Creates a <em>non-temporary</em> queue <em>non-durable</em> queue.
168        *
169        * @param address the queue will be bound to this address
170        * @param queueName the name of the queue
171        * @throws HornetQException in an exception occurs while creating the queue
172        */
173       void createQueue(String address, String queueName) throws HornetQException;
174    
175       /**
176        * Creates a <em>non-temporary</em> queue <em>non-durable</em> queue.
177        *
178        * @param address the queue will be bound to this address
179        * @param queueName the name of the queue
180        * @throws HornetQException in an exception occurs while creating the queue
181        */
182       void createQueue(SimpleString address, SimpleString queueName) throws HornetQException;
183    
184       /**
185        * Creates a <em>non-temporary</em> queue.
186        *
187        * @param address the queue will be bound to this address
188        * @param queueName the name of the queue
189        * @param durable whether the queue is durable or not
190        * @param filter only messages which match this filter will be put in the queue
191        * @throws HornetQException in an exception occurs while creating the queue
192        */
193       void createQueue(SimpleString address, SimpleString queueName, SimpleString filter, boolean durable) throws HornetQException;
194    
195       /**
196        * Creates a <em>non-temporary</em>queue.
197        *
198        * @param address the queue will be bound to this address
199        * @param queueName the name of the queue
200        * @param durable whether the queue is durable or not
201        * @param filter only messages which match this filter will be put in the queue
202        * @throws HornetQException in an exception occurs while creating the queue
203        */
204       void createQueue(String address, String queueName, String filter, boolean durable) throws HornetQException;
205    
206       /**
207        * Creates a <em>temporary</em> queue.
208        *
209        * @param address the queue will be bound to this address
210        * @param queueName the name of the queue
211        * @throws HornetQException in an exception occurs while creating the queue
212        */
213       void createTemporaryQueue(SimpleString address, SimpleString queueName) throws HornetQException;
214    
215       /**
216        * Creates a <em>temporary</em> queue.
217        *
218        * @param address the queue will be bound to this address
219        * @param queueName the name of the queue
220        * @throws HornetQException in an exception occurs while creating the queue
221        */
222       void createTemporaryQueue(String address, String queueName) throws HornetQException;
223    
224       /**
225        * Creates a <em>temporary</em> queue with a filter.
226        *
227        * @param address the queue will be bound to this address
228        * @param queueName the name of the queue
229        * @param filter only messages which match this filter will be put in the queue
230        * @throws HornetQException in an exception occurs while creating the queue
231        */
232       void createTemporaryQueue(SimpleString address, SimpleString queueName, SimpleString filter) throws HornetQException;
233    
234       /**
235        * Creates a <em>temporary</em> queue with a filter.
236        *
237        * @param address the queue will be bound to this address
238        * @param queueName the name of the queue
239        * @param filter only messages which match this filter will be put in the queue
240        * @throws HornetQException in an exception occurs while creating the queue
241        */
242       void createTemporaryQueue(String address, String queueName, String filter) throws HornetQException;
243    
244       /**
245        * Deletes the queue.
246        *
247        * @param queueName the name of the queue to delete
248        * @throws HornetQException if there is no queue for the given name or if the queue has consumers
249        */
250       void deleteQueue(SimpleString queueName) throws HornetQException;
251    
252       /**
253        * Deletes the queue.
254        *
255        * @param queueName the name of the queue to delete
256        * @throws HornetQException if there is no queue for the given name or if the queue has consumers
257        */
258       void deleteQueue(String queueName) throws HornetQException;
259    
260       // Consumer Operations -------------------------------------------
261    
262       /**
263        * Creates a ClientConsumer to consume message from the queue with the given name.
264        *
265        * @param queueName name of the queue to consume messages from
266        * @return a ClientConsumer
267        * @throws HornetQException if an exception occurs while creating the ClientConsumer
268        */
269       ClientConsumer createConsumer(SimpleString queueName) throws HornetQException;
270    
271       /**
272        * Creates a ClientConsumer to consume messages from the queue with the given name.
273        *
274        * @param queueName name of the queue to consume messages from
275        * @return a ClientConsumer
276        * @throws HornetQException if an exception occurs while creating the ClientConsumer
277        */
278       ClientConsumer createConsumer(String queueName) throws HornetQException;
279    
280       /**
281        * Creates a ClientConsumer to consume messages matching the filter from the queue with the given name.
282        *
283        * @param queueName name of the queue to consume messages from
284        * @param filter only messages which match this filter will be consumed
285        * @return a ClientConsumer
286        * @throws HornetQException if an exception occurs while creating the ClientConsumer
287        */
288       ClientConsumer createConsumer(SimpleString queueName, SimpleString filter) throws HornetQException;
289    
290       /**
291        * Creates a ClientConsumer to consume messages matching the filter from the queue with the given name.
292        *
293        * @param queueName name of the queue to consume messages from
294        * @param filter only messages which match this filter will be consumed
295        * @return a ClientConsumer
296        * @throws HornetQException if an exception occurs while creating the ClientConsumer
297        */
298       ClientConsumer createConsumer(String queueName, String filter) throws HornetQException;
299    
300       /**
301        * Creates a ClientConsumer to consume or browse messages from the queue with the given name.
302        * If <code>browseOnly</code> is <code>true</code>, the ClientConsumer will receive the messages from the queue
303        * but they will not be consumed (the messages will remain in the queue).
304        * If <code>browseOnly</code> is <code>false</code>, the ClientConsumer will behave like consume the messages from the queue and
305        * the messages will effectively be removed from the queue.
306        *
307        * @param queueName name of the queue to consume messages from
308        * @param browseOnly whether the ClientConsumer will only browse the queue or consume messages.
309        * @return a ClientConsumer
310        * @throws HornetQException if an exception occurs while creating the ClientConsumer
311        */
312       ClientConsumer createConsumer(SimpleString queueName, boolean browseOnly) throws HornetQException;
313    
314       /**
315        * Creates a ClientConsumer to consume or browse messages from the queue with the given name.
316        * If <code>browseOnly</code> is <code>true</code>, the ClientConsumer will receive the messages from the queue
317        * but they will not be consumed (the messages will remain in the queue).
318        * If <code>browseOnly</code> is <code>false</code>, the ClientConsumer will behave like consume the messages from the queue and
319        * the messages will effectively be removed from the queue.
320        *
321        * @param queueName name of the queue to consume messages from
322        * @param browseOnly whether the ClientConsumer will only browse the queue or consume messages.
323        * @return a ClientConsumer
324        * @throws HornetQException if an exception occurs while creating the ClientConsumer
325        */
326       ClientConsumer createConsumer(String queueName, boolean browseOnly) throws HornetQException;
327    
328       /**
329        * Creates a ClientConsumer to consume or browse messages matching the filter from the queue with the given name.
330        * If <code>browseOnly</code> is <code>true</code>, the ClientConsumer will receive the messages from the queue
331        * but they will not be consumed (the messages will remain in the queue).
332        * If <code>browseOnly</code> is <code>false</code>, the ClientConsumer will behave like consume the messages from the queue and
333        * the messages will effectively be removed from the queue.
334        *
335        * @param queueName name of the queue to consume messages from
336        * @param filter only messages which match this filter will be consumed
337        * @param browseOnly whether the ClientConsumer will only browse the queue or consume messages.
338        * @return a ClientConsumer
339        * @throws HornetQException if an exception occurs while creating the ClientConsumer
340        */
341       ClientConsumer createConsumer(String queueName, String filter, boolean browseOnly) throws HornetQException;
342    
343       /**
344        * Creates a ClientConsumer to consume or browse messages matching the filter from the queue with the given name.
345        * If <code>browseOnly</code> is <code>true</code>, the ClientConsumer will receive the messages from the queue
346        * but they will not be consumed (the messages will remain in the queue).
347        * If <code>browseOnly</code> is <code>false</code>, the ClientConsumer will behave like consume the messages from the queue and
348        * the messages will effectively be removed from the queue.
349        *
350        * @param queueName name of the queue to consume messages from
351        * @param filter only messages which match this filter will be consumed
352        * @param browseOnly whether the ClientConsumer will only browse the queue or consume messages.
353        * @return a ClientConsumer
354        * @throws HornetQException if an exception occurs while creating the ClientConsumer
355        */
356       ClientConsumer createConsumer(SimpleString queueName, SimpleString filter, boolean browseOnly) throws HornetQException;
357    
358       /**
359        * Creates a ClientConsumer to consume or browse messages matching the filter from the queue with the given name.
360        * If <code>browseOnly</code> is <code>true</code>, the ClientConsumer will receive the messages from the queue
361        * but they will not be consumed (the messages will remain in the queue).
362        * If <code>browseOnly</code> is <code>false</code>, the ClientConsumer will behave like consume the messages from the queue and
363        * the messages will effectively be removed from the queue.
364        *
365        * @param queueName name of the queue to consume messages from
366        * @param filter only messages which match this filter will be consumed
367        * @param windowSize the consumer window size
368        * @param maxRate the maximum rate to consume messages
369        * @param browseOnly whether the ClientConsumer will only browse the queue or consume messages.
370        * @return a ClientConsumer
371        * @throws HornetQException if an exception occurs while creating the ClientConsumer
372        */
373       ClientConsumer createConsumer(SimpleString queueName,
374                                     SimpleString filter,
375                                     int windowSize,
376                                     int maxRate,
377                                     boolean browseOnly) throws HornetQException;
378    
379       /**
380        * Creates a ClientConsumer to consume or browse messages matching the filter from the queue with the given name.
381        * If <code>browseOnly</code> is <code>true</code>, the ClientConsumer will receive the messages from the queue
382        * but they will not be consumed (the messages will remain in the queue).
383        * If <code>browseOnly</code> is <code>false</code>, the ClientConsumer will behave like consume the messages from the queue and
384        * the messages will effectively be removed from the queue.
385        *
386        * @param queueName name of the queue to consume messages from
387        * @param filter only messages which match this filter will be consumed
388        * @param windowSize the consumer window size
389        * @param maxRate the maximum rate to consume messages
390        * @param browseOnly whether the ClientConsumer will only browse the queue or consume messages.
391        * @return a ClientConsumer
392        * @throws HornetQException if an exception occurs while creating the ClientConsumer
393        */
394       ClientConsumer createConsumer(String queueName, String filter, int windowSize, int maxRate, boolean browseOnly) throws HornetQException;
395    
396       // Producer Operations -------------------------------------------
397    
398       /**
399        * Creates a producer with no default address.
400        * Address must be specified every time a message is sent
401        *
402        * @return a ClientProducer
403        *
404        * @see ClientProducer#send(SimpleString, org.hornetq.api.core.Message)
405        */
406       ClientProducer createProducer() throws HornetQException;
407    
408       /**
409        * Creates a producer which sends messages to the given address
410        *
411        * @param address the address to send messages to
412        * @return a ClientProducer
413        * @throws HornetQException if an exception occurs while creating the ClientProducer
414        */
415       ClientProducer createProducer(SimpleString address) throws HornetQException;
416    
417       /**
418        * Creates a producer which sends messages to the given address
419        *
420        * @param address the address to send messages to
421        * @return a ClientProducer
422        * @throws HornetQException if an exception occurs while creating the ClientProducer
423        */
424       ClientProducer createProducer(String address) throws HornetQException;
425    
426       /**
427        * Creates a producer which sends messages to the given address
428        *
429        * @param address the address to send messages to
430        * @param rate the producer rate
431        * @return a ClientProducer
432        * @throws HornetQException if an exception occurs while creating the ClientProducer
433        */
434       ClientProducer createProducer(SimpleString address, int rate) throws HornetQException;
435    
436       // Message operations --------------------------------------------
437    
438       /**
439        * Creates a ClientMessage.
440        *
441        * @param durable whether the created message is durable or not
442        * @return a ClientMessage
443        */
444       ClientMessage createMessage(boolean durable);
445    
446       /**
447        * Creates a ClientMessage.
448        *
449        * @param type type of the message
450        * @param durable whether the created message is durable or not
451        * @return a ClientMessage
452        */
453       ClientMessage createMessage(byte type, boolean durable);
454    
455       /**
456        * Creates a ClientMessage.
457        *
458        * @param type type of the message
459        * @param durable whether the created message is durable or not
460        * @param expiration the message expiration
461        * @param timestamp the message timestamp
462        * @param priority the message priority (between 0 and 9 inclusive)
463        * @return a ClientMessage
464        */
465       ClientMessage createMessage(byte type, boolean durable, long expiration, long timestamp, byte priority);
466    
467       // Query operations ----------------------------------------------
468    
469       /**
470        * Queries information on a queue.
471        *
472        * @param queueName the name of the queue to query
473        * @return a QueueQuery containing information on the given queue
474        *
475        * @throws HornetQException if an exception occurs while querying the queue
476        */
477       QueueQuery queueQuery(SimpleString queueName) throws HornetQException;
478    
479       /**
480        * Queries information on a binding.
481        *
482        * @param address the address of the biding to query
483        * @return a BindingQuery containing information on the binding attached to the given address
484        *
485        * @throws HornetQException if an exception occurs while querying the binding
486        */
487       BindingQuery bindingQuery(SimpleString address) throws HornetQException;
488    
489       // Transaction operations ----------------------------------------
490    
491       /**
492        * Returns the XAResource associated to the session.
493        *
494        * @return the XAResource associated to the session
495        */
496       XAResource getXAResource();
497    
498       /**
499        * Return <code>true</code> if the session supports XA, <code>false</code> else.
500        *
501        * @return <code>true</code> if the session supports XA, <code>false</code> else.
502        */
503       boolean isXA();
504    
505       /**
506        * Commits the current transaction.
507        *
508        * @throws HornetQException if an exception occurs while committing the transaction
509        */
510       void commit() throws HornetQException;
511    
512       /**
513        * Rolls back the current transaction.
514        *
515        * @throws HornetQException if an exception occurs while rolling back the transaction
516        */
517       void rollback() throws HornetQException;
518    
519       /**
520        * Rolls back the current transaction.
521        *
522        * @param considerLastMessageAsDelivered the first message on deliveringMessage Buffer is considered as delivered
523        *
524        * @throws HornetQException if an exception occurs while rolling back the transaction
525        */
526       void rollback(boolean considerLastMessageAsDelivered) throws HornetQException;
527    
528       /**
529        * Returns <code>true</code> if the current transaction has been flagged to rollback, <code>false</code> else.
530        *
531        * @return <code>true</code> if the current transaction has been flagged to rollback, <code>false</code> else.
532        */
533       boolean isRollbackOnly();
534    
535       /**
536        * Returns whether the session will <em>automatically</em> commit its transaction every time a message is sent
537        * by a ClientProducer created by this session, <code>false</code> else
538        *
539        * @return <code>true</code> if the session <em>automatically</em> commit its transaction every time a message is sent, <code>false</code> else
540        */
541       boolean isAutoCommitSends();
542    
543       /**
544        * Returns whether the session will <em>automatically</em> commit its transaction every time a message is acknowledged
545        * by a ClientConsumer created by this session, <code>false</code> else
546        *
547        * @return <code>true</code> if the session <em>automatically</em> commit its transaction every time a message is acknowledged, <code>false</code> else
548        */
549       boolean isAutoCommitAcks();
550    
551       /**
552        * Returns whether the ClientConsumer created by the session will <em>block</em> when they acknowledge a message.
553        *
554        * @return <code>true</code> if the session's ClientConsumer block when they acknowledge a message, <code>false</code> else
555        */
556       boolean isBlockOnAcknowledge();
557    
558       /**
559        * Sets a <code>SendAcknowledgementHandler</code> for this session.
560        *
561        * @param handler a SendAcknowledgementHandler
562        */
563       void setSendAcknowledgementHandler(SendAcknowledgementHandler handler);
564    
565       /**
566        * Attach any metadata to the session.
567        * @throws HornetQException
568        */
569       void addMetaData(String key, String data) throws HornetQException;
570    
571       /**
572        * Attach any metadata to the session. Throws an exception if there's already a metadata available.
573        * You can use this metadata to ensure that there is no other session with the same meta-data you are passing as an argument.
574        * This is useful to simulate unique client-ids, where you may want to avoid multiple instances of your client application connected.
575        *
576        * @throws HornetQException
577        */
578       void addUniqueMetaData(String key, String data) throws HornetQException;
579    
580       /**
581        * Attach any metadata to the session.
582        * Sends a Metadata using the older version
583        * @deprecated Use {@link ClientSession#addMetaData(String, String)}
584        * @throws HornetQException
585        */
586       void addMetaDataV1(String key, String data) throws HornetQException;
587    }