    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    }