## org.hornetq.api.core.client
Interface ClientSession

All Superinterfaces:
  XAResource

    public interface ClientSession

extends XAResource

A ClientSession is a single-thread object required for producing and consuming messages.

Author:
  Tim Fox, Clebert Suconic, Andy Taylor, Jeff Mesnil

Nested Class Summary
`static interface` `ClientSession.BindingQuery` Information returned by a binding query
`static interface` `ClientSession.QueueQuery` Information returned by a queue query

Field Summary

Fields inherited from interface javax.transaction.xa.XAResource
`TMENDRSCAN, TMFAIL, TMJOIN, TMNOFLAGS, TMONEPHASE, TMRESUME, TMSTARTRSCAN, TMSUCCESS, TMSUSPEND, XA_OK, XA_RDONLY`

Method Summary
`void` `addFailureListener(SessionFailureListener listener)` Adds a FailureListener to the session which is notified if a failure occurs on the session.
`void` `addMetaData(String key, String data)` Attach any metadata to the session.
`void` `addMetaDataV1(String key, String data)` Deprecated. Use `addMetaData(String, String)`
`void` `addUniqueMetaData(String key, String data)` Attach any metadata to the session.
`ClientSession.BindingQuery` `bindingQuery(SimpleString address)` Queries information on a binding.
`void` `close()` Closes the session.
`void` `commit()` Commits the current transaction.
`ClientConsumer` `createConsumer(SimpleString queueName)` Creates a ClientConsumer to consume message from the queue with the given name.
`ClientConsumer` `createConsumer(SimpleString queueName, boolean browseOnly)` Creates a ClientConsumer to consume or browse messages from the queue with the given name.
`ClientConsumer` `createConsumer(SimpleString queueName, SimpleString filter)` Creates a ClientConsumer to consume messages matching the filter from the queue with the given name.
`ClientConsumer` `createConsumer(SimpleString queueName, SimpleString filter, boolean browseOnly)` Creates a ClientConsumer to consume or browse messages matching the filter from the queue with the given name.
`ClientConsumer` `createConsumer(SimpleString queueName, SimpleString filter, int windowSize, int maxRate, boolean browseOnly)` Creates a ClientConsumer to consume or browse messages matching the filter from the queue with the given name.
`ClientConsumer` `createConsumer(String queueName)` Creates a ClientConsumer to consume messages from the queue with the given name.
`ClientConsumer` `createConsumer(String queueName, boolean browseOnly)` Creates a ClientConsumer to consume or browse messages from the queue with the given name.
`ClientConsumer` `createConsumer(String queueName, String filter)` Creates a ClientConsumer to consume messages matching the filter from the queue with the given name.
`ClientConsumer` `createConsumer(String queueName, String filter, boolean browseOnly)` Creates a ClientConsumer to consume or browse messages matching the filter from the queue with the given name.
`ClientConsumer` `createConsumer(String queueName, String filter, int windowSize, int maxRate, boolean browseOnly)` Creates a ClientConsumer to consume or browse messages matching the filter from the queue with the given name.
`ClientMessage` `createMessage(boolean durable)` Creates a ClientMessage.
`ClientMessage` `createMessage(byte type, boolean durable)` Creates a ClientMessage.
`ClientMessage` `createMessage(byte type, boolean durable, long expiration, long timestamp, byte priority)` Creates a ClientMessage.
`ClientProducer` `createProducer()` Creates a producer with no default address.
`ClientProducer` `createProducer(SimpleString address)` Creates a producer which sends messages to the given address
`ClientProducer` `createProducer(SimpleString address, int rate)` Creates a producer which sends messages to the given address
`ClientProducer` `createProducer(String address)` Creates a producer which sends messages to the given address
`void` `createQueue(SimpleString address, SimpleString queueName)` Creates a non-temporary queue non-durable queue.
`void` `createQueue(SimpleString address, SimpleString queueName, boolean durable)` Creates a non-temporary queue.
`void` `createQueue(SimpleString address, SimpleString queueName, SimpleString filter, boolean durable)` Creates a non-temporary queue.
`void` `createQueue(String address, String queueName)` Creates a non-temporary queue non-durable queue.
`void` `createQueue(String address, String queueName, boolean durable)` Creates a non-temporary queue.
`void` `createQueue(String address, String queueName, String filter, boolean durable)` Creates a non-temporaryqueue.
`void` `createTemporaryQueue(SimpleString address, SimpleString queueName)` Creates a temporary queue.
`void` `createTemporaryQueue(SimpleString address, SimpleString queueName, SimpleString filter)` Creates a temporary queue with a filter.
`void` `createTemporaryQueue(String address, String queueName)` Creates a temporary queue.
`void` `createTemporaryQueue(String address, String queueName, String filter)` Creates a temporary queue with a filter.
`void` `deleteQueue(SimpleString queueName)` Deletes the queue.
`void` `deleteQueue(String queueName)` Deletes the queue.
`int` `getVersion()` Returns the server's incrementingVersion.
`XAResource` `getXAResource()` Returns the XAResource associated to the session.
`boolean` `isAutoCommitAcks()` Returns whether the session will automatically commit its transaction every time a message is acknowledged by a ClientConsumer created by this session, `false` else
`boolean` `isAutoCommitSends()` Returns whether the session will automatically commit its transaction every time a message is sent by a ClientProducer created by this session, `false` else
`boolean` `isBlockOnAcknowledge()` Returns whether the ClientConsumer created by the session will block when they acknowledge a message.
`boolean` `isClosed()` Returns whether the session is closed or not.
`boolean` `isRollbackOnly()` Returns `true` if the current transaction has been flagged to rollback, `false` else.
`boolean` `isXA()` Return `true` if the session supports XA, `false` else.
`ClientSession.QueueQuery` `queueQuery(SimpleString queueName)` Queries information on a queue.
`boolean` `removeFailureListener(SessionFailureListener listener)` Removes a FailureListener to the session.
`void` `rollback()` Rolls back the current transaction.
`void` `rollback(boolean considerLastMessageAsDelivered)` Rolls back the current transaction.
`void` `setSendAcknowledgementHandler(SendAcknowledgementHandler handler)` Sets a `SendAcknowledgementHandler` for this session.
`void` `start()` Starts the session.
`void` `stop()` Stops the session.

Methods inherited from interface javax.transaction.xa.XAResource
`commit, end, forget, getTransactionTimeout, isSameRM, prepare, recover, rollback, setTransactionTimeout, start`

Method Detail

### start

    void start()
               throws HornetQException

  Starts the session. The session must be started before ClientConsumers created by the session can consume messages from the queue.

  Throws:
    `HornetQException` - if an exception occurs while starting the session

### stop

    void stop()
              throws HornetQException

  Stops the session. ClientConsumers created by the session can not consume messages when the session is stopped.

  Throws:
    `HornetQException` - if an exception occurs while stopping the session

### close

    void close()
               throws HornetQException

  Closes the session.

  Throws:
    `HornetQException` - if an exception occurs while closing the session

### isClosed

    boolean isClosed()

  Returns whether the session is closed or not.

  Returns:
    `true` if the session is closed, `false` else

### addFailureListener

    void addFailureListener(SessionFailureListener listener)

  Adds a FailureListener to the session which is notified if a failure occurs on the session.

  Parameters:
    `listener` - the listener to add

### removeFailureListener

    boolean removeFailureListener(SessionFailureListener listener)

  Removes a FailureListener to the session.

  Parameters:
    `listener` - the listener to remove
  Returns:
    `true` if the listener was removed, `false` else

### getVersion

    int getVersion()

  Returns the server's incrementingVersion.

  Returns:
    the server's `incrementingVersion`

### createQueue

    void createQueue(SimpleString address,
                     SimpleString queueName,
                     boolean durable)
                     throws HornetQException

  Creates a non-temporary queue.

  Parameters:
    `address` - the queue will be bound to this address
    `queueName` - the name of the queue
    `durable` - whether the queue is durable or not
  Throws:
    `HornetQException` - in an exception occurs while creating the queue

### createQueue

    void createQueue(String address,
                     String queueName,
                     boolean durable)
                     throws HornetQException

  Creates a non-temporary queue.

  Parameters:
    `address` - the queue will be bound to this address
    `queueName` - the name of the queue
    `durable` - whether the queue is durable or not
  Throws:
    `HornetQException` - in an exception occurs while creating the queue

### createQueue

    void createQueue(String address,
                     String queueName)
                     throws HornetQException

  Creates a non-temporary queue non-durable queue.

  Parameters:
    `address` - the queue will be bound to this address
    `queueName` - the name of the queue
  Throws:
    `HornetQException` - in an exception occurs while creating the queue

### createQueue

    void createQueue(SimpleString address,
                     SimpleString queueName)
                     throws HornetQException

  Creates a non-temporary queue non-durable queue.

  Parameters:
    `address` - the queue will be bound to this address
    `queueName` - the name of the queue
  Throws:
    `HornetQException` - in an exception occurs while creating the queue

### createQueue

    void createQueue(SimpleString address,
                     SimpleString queueName,
                     SimpleString filter,
                     boolean durable)
                     throws HornetQException

  Creates a non-temporary queue.

  Parameters:
    `address` - the queue will be bound to this address
    `queueName` - the name of the queue
    `durable` - whether the queue is durable or not
    `filter` - only messages which match this filter will be put in the queue
  Throws:
    `HornetQException` - in an exception occurs while creating the queue

### createQueue

    void createQueue(String address,
                     String queueName,
                     String filter,
                     boolean durable)
                     throws HornetQException

  Creates a non-temporaryqueue.

  Parameters:
    `address` - the queue will be bound to this address
    `queueName` - the name of the queue
    `durable` - whether the queue is durable or not
    `filter` - only messages which match this filter will be put in the queue
  Throws:
    `HornetQException` - in an exception occurs while creating the queue

### createTemporaryQueue

    void createTemporaryQueue(SimpleString address,
                              SimpleString queueName)
                              throws HornetQException

  Creates a temporary queue.

  Parameters:
    `address` - the queue will be bound to this address
    `queueName` - the name of the queue
  Throws:
    `HornetQException` - in an exception occurs while creating the queue

### createTemporaryQueue

    void createTemporaryQueue(String address,
                              String queueName)
                              throws HornetQException

  Creates a temporary queue.

  Parameters:
    `address` - the queue will be bound to this address
    `queueName` - the name of the queue
  Throws:
    `HornetQException` - in an exception occurs while creating the queue

### createTemporaryQueue

    void createTemporaryQueue(SimpleString address,
                              SimpleString queueName,
                              SimpleString filter)
                              throws HornetQException

  Creates a temporary queue with a filter.

  Parameters:
    `address` - the queue will be bound to this address
    `queueName` - the name of the queue
    `filter` - only messages which match this filter will be put in the queue
  Throws:
    `HornetQException` - in an exception occurs while creating the queue

### createTemporaryQueue

    void createTemporaryQueue(String address,
                              String queueName,
                              String filter)
                              throws HornetQException

  Creates a temporary queue with a filter.

  Parameters:
    `address` - the queue will be bound to this address
    `queueName` - the name of the queue
    `filter` - only messages which match this filter will be put in the queue
  Throws:
    `HornetQException` - in an exception occurs while creating the queue

### deleteQueue

    void deleteQueue(SimpleString queueName)
                     throws HornetQException

  Deletes the queue.

  Parameters:
    `queueName` - the name of the queue to delete
  Throws:
    `HornetQException` - if there is no queue for the given name or if the queue has consumers

### deleteQueue

    void deleteQueue(String queueName)
                     throws HornetQException

  Deletes the queue.

  Parameters:
    `queueName` - the name of the queue to delete
  Throws:
    `HornetQException` - if there is no queue for the given name or if the queue has consumers

### createConsumer

    ClientConsumer createConsumer(SimpleString queueName)
                                  throws HornetQException

  Creates a ClientConsumer to consume message from the queue with the given name.

  Parameters:
    `queueName` - name of the queue to consume messages from
  Returns:
    a ClientConsumer
  Throws:
    `HornetQException` - if an exception occurs while creating the ClientConsumer

### createConsumer

    ClientConsumer createConsumer(String queueName)
                                  throws HornetQException

  Creates a ClientConsumer to consume messages from the queue with the given name.

  Parameters:
    `queueName` - name of the queue to consume messages from
  Returns:
    a ClientConsumer
  Throws:
    `HornetQException` - if an exception occurs while creating the ClientConsumer

### createConsumer

    ClientConsumer createConsumer(SimpleString queueName,
                                  SimpleString filter)
                                  throws HornetQException

  Creates a ClientConsumer to consume messages matching the filter from the queue with the given name.

  Parameters:
    `queueName` - name of the queue to consume messages from
    `filter` - only messages which match this filter will be consumed
  Returns:
    a ClientConsumer
  Throws:
    `HornetQException` - if an exception occurs while creating the ClientConsumer

### createConsumer

    ClientConsumer createConsumer(String queueName,
                                  String filter)
                                  throws HornetQException

  Creates a ClientConsumer to consume messages matching the filter from the queue with the given name.

  Parameters:
    `queueName` - name of the queue to consume messages from
    `filter` - only messages which match this filter will be consumed
  Returns:
    a ClientConsumer
  Throws:
    `HornetQException` - if an exception occurs while creating the ClientConsumer

### createConsumer

    ClientConsumer createConsumer(SimpleString queueName,
                                  boolean browseOnly)
                                  throws HornetQException

  Creates a ClientConsumer to consume or browse messages from the queue with the given name. If `browseOnly` is `true`, the ClientConsumer will receive the messages from the queue but they will not be consumed (the messages will remain in the queue). If `browseOnly` is `false`, the ClientConsumer will behave like consume the messages from the queue and the messages will effectively be removed from the queue.

  Parameters:
    `queueName` - name of the queue to consume messages from
    `browseOnly` - whether the ClientConsumer will only browse the queue or consume messages.
  Returns:
    a ClientConsumer
  Throws:
    `HornetQException` - if an exception occurs while creating the ClientConsumer

### createConsumer

    ClientConsumer createConsumer(String queueName,
                                  boolean browseOnly)
                                  throws HornetQException

  Creates a ClientConsumer to consume or browse messages from the queue with the given name. If `browseOnly` is `true`, the ClientConsumer will receive the messages from the queue but they will not be consumed (the messages will remain in the queue). If `browseOnly` is `false`, the ClientConsumer will behave like consume the messages from the queue and the messages will effectively be removed from the queue.

  Parameters:
    `queueName` - name of the queue to consume messages from
    `browseOnly` - whether the ClientConsumer will only browse the queue or consume messages.
  Returns:
    a ClientConsumer
  Throws:
    `HornetQException` - if an exception occurs while creating the ClientConsumer

### createConsumer

    ClientConsumer createConsumer(String queueName,
                                  String filter,
                                  boolean browseOnly)
                                  throws HornetQException

  Creates a ClientConsumer to consume or browse messages matching the filter from the queue with the given name. If `browseOnly` is `true`, the ClientConsumer will receive the messages from the queue but they will not be consumed (the messages will remain in the queue). If `browseOnly` is `false`, the ClientConsumer will behave like consume the messages from the queue and the messages will effectively be removed from the queue.

  Parameters:
    `queueName` - name of the queue to consume messages from
    `filter` - only messages which match this filter will be consumed
    `browseOnly` - whether the ClientConsumer will only browse the queue or consume messages.
  Returns:
    a ClientConsumer
  Throws:
    `HornetQException` - if an exception occurs while creating the ClientConsumer

### createConsumer

    ClientConsumer createConsumer(SimpleString queueName,
                                  SimpleString filter,
                                  boolean browseOnly)
                                  throws HornetQException

  Creates a ClientConsumer to consume or browse messages matching the filter from the queue with the given name. If `browseOnly` is `true`, the ClientConsumer will receive the messages from the queue but they will not be consumed (the messages will remain in the queue). If `browseOnly` is `false`, the ClientConsumer will behave like consume the messages from the queue and the messages will effectively be removed from the queue.

  Parameters:
    `queueName` - name of the queue to consume messages from
    `filter` - only messages which match this filter will be consumed
    `browseOnly` - whether the ClientConsumer will only browse the queue or consume messages.
  Returns:
    a ClientConsumer
  Throws:
    `HornetQException` - if an exception occurs while creating the ClientConsumer

### createConsumer

    ClientConsumer createConsumer(SimpleString queueName,
                                  SimpleString filter,
                                  int windowSize,
                                  int maxRate,
                                  boolean browseOnly)
                                  throws HornetQException

  Creates a ClientConsumer to consume or browse messages matching the filter from the queue with the given name. If `browseOnly` is `true`, the ClientConsumer will receive the messages from the queue but they will not be consumed (the messages will remain in the queue). If `browseOnly` is `false`, the ClientConsumer will behave like consume the messages from the queue and the messages will effectively be removed from the queue.

  Parameters:
    `queueName` - name of the queue to consume messages from
    `filter` - only messages which match this filter will be consumed
    `windowSize` - the consumer window size
    `maxRate` - the maximum rate to consume messages
    `browseOnly` - whether the ClientConsumer will only browse the queue or consume messages.
  Returns:
    a ClientConsumer
  Throws:
    `HornetQException` - if an exception occurs while creating the ClientConsumer

### createConsumer

    ClientConsumer createConsumer(String queueName,
                                  String filter,
                                  int windowSize,
                                  int maxRate,
                                  boolean browseOnly)
                                  throws HornetQException

  Creates a ClientConsumer to consume or browse messages matching the filter from the queue with the given name. If `browseOnly` is `true`, the ClientConsumer will receive the messages from the queue but they will not be consumed (the messages will remain in the queue). If `browseOnly` is `false`, the ClientConsumer will behave like consume the messages from the queue and the messages will effectively be removed from the queue.

  Parameters:
    `queueName` - name of the queue to consume messages from
    `filter` - only messages which match this filter will be consumed
    `windowSize` - the consumer window size
    `maxRate` - the maximum rate to consume messages
    `browseOnly` - whether the ClientConsumer will only browse the queue or consume messages.
  Returns:
    a ClientConsumer
  Throws:
    `HornetQException` - if an exception occurs while creating the ClientConsumer

### createProducer

    ClientProducer createProducer()
                                  throws HornetQException

  Creates a producer with no default address. Address must be specified every time a message is sent

  Returns:
    a ClientProducer
  Throws:
    `HornetQException`
  See Also:
    `ClientProducer.send(SimpleString, org.hornetq.api.core.Message)`

### createProducer

    ClientProducer createProducer(SimpleString address)
                                  throws HornetQException

  Creates a producer which sends messages to the given address

  Parameters:
    `address` - the address to send messages to
  Returns:
    a ClientProducer
  Throws:
    `HornetQException` - if an exception occurs while creating the ClientProducer

### createProducer

    ClientProducer createProducer(String address)
                                  throws HornetQException

  Creates a producer which sends messages to the given address

  Parameters:
    `address` - the address to send messages to
  Returns:
    a ClientProducer
  Throws:
    `HornetQException` - if an exception occurs while creating the ClientProducer

### createProducer

    ClientProducer createProducer(SimpleString address,
                                  int rate)
                                  throws HornetQException

  Creates a producer which sends messages to the given address

  Parameters:
    `address` - the address to send messages to
    `rate` - the producer rate
  Returns:
    a ClientProducer
  Throws:
    `HornetQException` - if an exception occurs while creating the ClientProducer

### createMessage

    ClientMessage createMessage(boolean durable)

  Creates a ClientMessage.

  Parameters:
    `durable` - whether the created message is durable or not
  Returns:
    a ClientMessage

### createMessage

    ClientMessage createMessage(byte type,
                                boolean durable)

  Creates a ClientMessage.

  Parameters:
    `type` - type of the message
    `durable` - whether the created message is durable or not
  Returns:
    a ClientMessage

### createMessage

    ClientMessage createMessage(byte type,
                                boolean durable,
                                long expiration,
                                long timestamp,
                                byte priority)

  Creates a ClientMessage.

  Parameters:
    `type` - type of the message
    `durable` - whether the created message is durable or not
    `expiration` - the message expiration
    `timestamp` - the message timestamp
    `priority` - the message priority (between 0 and 9 inclusive)
  Returns:
    a ClientMessage

### queueQuery

    ClientSession.QueueQuery queueQuery(SimpleString queueName)
                                        throws HornetQException

  Queries information on a queue.

  Parameters:
    `queueName` - the name of the queue to query
  Returns:
    a QueueQuery containing information on the given queue
  Throws:
    `HornetQException` - if an exception occurs while querying the queue

### bindingQuery

    ClientSession.BindingQuery bindingQuery(SimpleString address)
                                            throws HornetQException

  Queries information on a binding.

  Parameters:
    `address` - the address of the biding to query
  Returns:
    a BindingQuery containing information on the binding attached to the given address
  Throws:
    `HornetQException` - if an exception occurs while querying the binding

### getXAResource

    XAResource getXAResource()

  Returns the XAResource associated to the session.

  Returns:
    the XAResource associated to the session

### isXA

    boolean isXA()

  Return `true` if the session supports XA, `false` else.

  Returns:
    `true` if the session supports XA, `false` else.

### commit

    void commit()
                throws HornetQException

  Commits the current transaction.

  Throws:
    `HornetQException` - if an exception occurs while committing the transaction

### rollback

    void rollback()
                  throws HornetQException

  Rolls back the current transaction.

  Throws:
    `HornetQException` - if an exception occurs while rolling back the transaction

### rollback

    void rollback(boolean considerLastMessageAsDelivered)
                  throws HornetQException

  Rolls back the current transaction.

  Parameters:
    `considerLastMessageAsDelivered` - the first message on deliveringMessage Buffer is considered as delivered
  Throws:
    `HornetQException` - if an exception occurs while rolling back the transaction

### isRollbackOnly

    boolean isRollbackOnly()

  Returns `true` if the current transaction has been flagged to rollback, `false` else.

  Returns:
    `true` if the current transaction has been flagged to rollback, `false` else.

### isAutoCommitSends

    boolean isAutoCommitSends()

  Returns whether the session will automatically commit its transaction every time a message is sent by a ClientProducer created by this session, `false` else

  Returns:
    `true` if the session automatically commit its transaction every time a message is sent, `false` else

### isAutoCommitAcks

    boolean isAutoCommitAcks()

  Returns whether the session will automatically commit its transaction every time a message is acknowledged by a ClientConsumer created by this session, `false` else

  Returns:
    `true` if the session automatically commit its transaction every time a message is acknowledged, `false` else

### isBlockOnAcknowledge

    boolean isBlockOnAcknowledge()

  Returns whether the ClientConsumer created by the session will block when they acknowledge a message.

  Returns:
    `true` if the session's ClientConsumer block when they acknowledge a message, `false` else

### setSendAcknowledgementHandler

    void setSendAcknowledgementHandler(SendAcknowledgementHandler handler)

  Sets a `SendAcknowledgementHandler` for this session.

  Parameters:
    `handler` - a SendAcknowledgementHandler

### addMetaData

    void addMetaData(String key,
                     String data)
                     throws HornetQException

  Attach any metadata to the session.

  Throws:
    `HornetQException`

### addUniqueMetaData

    void addUniqueMetaData(String key,
                           String data)
                           throws HornetQException

  Attach any metadata to the session. Throws an exception if there's already a metadata available. You can use this metadata to ensure that there is no other session with the same meta-data you are passing as an argument. This is useful to simulate unique client-ids, where you may want to avoid multiple instances of your client application connected.

  Throws:
    `HornetQException`

### addMetaDataV1

    void addMetaDataV1(String key,
                       String data)
                       throws HornetQException

  Deprecated. Use `addMetaData(String, String)`

  Attach any metadata to the session. Sends a Metadata using the older version

  Throws:
    `HornetQException`

Copyright © 2009 Red Hat Inc. All Rights Reserved.