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 }