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
014package org.hornetq.api.core.client;
015
016import java.util.List;
017
018import javax.transaction.xa.XAResource;
019
020import org.hornetq.api.core.HornetQException;
021import 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 */
032public 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}