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}