[hornetq-commits] JBoss hornetq SVN: r8337 - trunk/src/main/org/hornetq/core/client.

Author: jmesnil Date: 2009-11-20 09:20:03 -0500 (Fri, 20 Nov 2009) New Revision: 8337 Modified: trunk/src/main/org/hornetq/core/client/ClientSession.java Log: HORNETQ-186: Javadoc for Core API * added javadoc to ClientSession interface Modified: trunk/src/main/org/hornetq/core/client/ClientSession.java =================================================================== --- trunk/src/main/org/hornetq/core/client/ClientSession.java 2009-11-20 12:47:17 UTC (rev 8336) +++ trunk/src/main/org/hornetq/core/client/ClientSession.java 2009-11-20 14:20:03 UTC (rev 8337) @@ -16,153 +16,527 @@ import javax.transaction.xa.XAResource; import org.hornetq.core.exception.HornetQException; -import org.hornetq.core.remoting.FailureListener; import org.hornetq.core.remoting.impl.wireformat.SessionBindingQueryResponseMessage; import org.hornetq.core.remoting.impl.wireformat.SessionQueueQueryResponseMessage; import org.hornetq.core.remoting.spi.HornetQBuffer; import org.hornetq.utils.SimpleString; -/* - * +/** * @author <a href="mailto:tim.fox@jboss.com">Tim Fox</a> - * * @author <a href="mailto:clebert.suconic@jboss.org">Clebert Suconic</a> - * * @author <a href="mailto:ataylor@redhat.com">Andy Taylor</a> - * * @author <a href=&quot;jmesnil(a)redhat.com&quot;&gt;Jeff Mesnil</a> */ public interface ClientSession extends XAResource { + // Lifecycle operations ------------------------------------------ + /** - * Queues created by this method are <em>not</em> temporary + * Start 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 */ + void start() throws HornetQException; + + /** + * Stop 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 + */ + void stop() throws HornetQException; + + /** + * Close the session. + * + * @throws HornetQException if an exception occurs while closing the session + */ + void close() throws HornetQException; + + /** + * Indicate if the session is closed or not. + * + * @return <code>true</code> if the session is closed, <code>false</code> else + */ + boolean isClosed(); + + /** + * Add a FailureListener to the session which is notified if a failure occurs on the session. + * + * @param listener the listener to add + */ + void addFailureListener(SessionFailureListener listener); + + /** + * Remove a FailureListener to the session. + * + * @param listener the listener to remove + * @return <code>true</code> if the listener was removed, <code>false</code> else + */ + boolean removeFailureListener(SessionFailureListener listener); + + /** + * Returns the server's incrementingVersion. + * + * @return the server's <code>incrementingVersion</code> + */ + int getVersion(); + + // Queue Operations ---------------------------------------------- + + /** + * Create a queue. The created queue is <em>not</em> temporary. + * + * @param address the queue will be bound to this address + * @param queueName the name of the queue + * @param durable whether the queue is durable or not + * @throws HornetQException in an exception occurs while creating the queue + */ void createQueue(SimpleString address, SimpleString queueName, boolean durable) throws HornetQException; /** - * Queues created by this method are <em>not</em> temporary + * Create a queue. The created queue is <em>not</em> temporary. + * + * @param address the queue will be bound to this address + * @param queueName the name of the queue + * @param durable whether the queue is durable or not + * @throws HornetQException in an exception occurs while creating the queue */ + void createQueue(String address, String queueName, boolean durable) throws HornetQException; + + /** + * Create a queue. The created queue is <em>not</em> temporary and <em>not</em> durable. + * + * @param address the queue will be bound to this address + * @param queueName the name of the queue + * @throws HornetQException in an exception occurs while creating the queue + */ void createQueue(String address, String queueName) throws HornetQException; - void createQueue(String address, String queueName, boolean durable) throws HornetQException; + /** + * Create a queue. The created queue is <em>not</em> temporary. + * + * @param address the queue will be bound to this address + * @param queueName the name of the queue + * @param durable whether the queue is durable or not + * @param filter only messages which match this filter will be put in the queue + * @throws HornetQException in an exception occurs while creating the queue + */ + void createQueue(SimpleString address, SimpleString queueName, SimpleString filter, boolean durable) throws HornetQException; - void createQueue(SimpleString address, SimpleString queueName, SimpleString filterString, boolean durable) throws HornetQException; + /** + * Create a queue. The created queue is <em>not</em> temporary. + * + * @param address the queue will be bound to this address + * @param queueName the name of the queue + * @param durable whether the queue is durable or not + * @param filter only messages which match this filter will be put in the queue + * @throws HornetQException in an exception occurs while creating the queue + */ + void createQueue(String address, String queueName, String filter, boolean durable) throws HornetQException; - void createQueue(String address, String queueName, String filterString, boolean durable) throws HornetQException; - + /** + * Create a <em>temporary</em> queue. + * + * @param address the queue will be bound to this address + * @param queueName the name of the queue + * @throws HornetQException in an exception occurs while creating the queue + */ void createTemporaryQueue(SimpleString address, SimpleString queueName) throws HornetQException; + /** + * Create a <em>temporary</em> queue. + * + * @param address the queue will be bound to this address + * @param queueName the name of the queue + * @throws HornetQException in an exception occurs while creating the queue + */ void createTemporaryQueue(String address, String queueName) throws HornetQException; + /** + * Create a <em>temporary</em> queue with a filter. + * + * @param address the queue will be bound to this address + * @param queueName the name of the queue + * @param filterString only messages which match this filter will be put in the queue + * @throws HornetQException in an exception occurs while creating the queue + */ void createTemporaryQueue(SimpleString address, SimpleString queueName, SimpleString filter) throws HornetQException; + /** + * Create a <em>temporary</em> queue with a filter. + * + * @param address the queue will be bound to this address + * @param queueName the name of the queue + * @param filterString only messages which match this filter will be put in the queue + * @throws HornetQException in an exception occurs while creating the queue + */ void createTemporaryQueue(String address, String queueName, String filter) throws HornetQException; + /** + * Delete the queue. + * + * @param 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 + */ void deleteQueue(SimpleString queueName) throws HornetQException; + /** + * Delete the queue. + * + * @param 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 + */ void deleteQueue(String queueName) throws HornetQException; + // Consumer Operations ------------------------------------------- + + /** + * Create a ClientConsumer to consume message from the queue with the given name. + * + * @param queueName name of the queue to consume messages from + * @return a ClientConsumer + * @throws HornetQException if an exception occurs while creating the ClientConsumer + */ ClientConsumer createConsumer(SimpleString queueName) throws HornetQException; + /** + * Create a ClientConsumer to consume messages from the queue with the given name. + * + * @param queueName name of the queue to consume messages from + * @return a ClientConsumer + * @throws HornetQException if an exception occurs while creating the ClientConsumer + */ + ClientConsumer createConsumer(String queueName) throws HornetQException; + + /** + * Create a ClientConsumer to consume messages matching the filter from the queue with the given name. + * + * @param queueName name of the queue to consume messages from + * @param filter only messages which match this filter will be consumed + * @return a ClientConsumer + * @throws HornetQException if an exception occurs while creating the ClientConsumer + */ ClientConsumer createConsumer(SimpleString queueName, SimpleString filterString) throws HornetQException; - ClientConsumer createConsumer(SimpleString queueName, SimpleString filterString, boolean browseOnly) throws HornetQException; + /** + * Create a ClientConsumer to consume messages matching the filter from the queue with the given name. + * + * @param queueName name of the queue to consume messages from + * @param filter only messages which match this filter will be consumed + * @return a ClientConsumer + * @throws HornetQException if an exception occurs while creating the ClientConsumer + */ + ClientConsumer createConsumer(String queueName, String filterString) throws HornetQException; + /** + * Create a ClientConsumer to consume or browse messages from the queue with the given name. + * If <code>browseOnly</code> is <code>true</code>, the ClientConsumer will receive the messages from the queue + * but they will not be consumed (the messages will remain in the queue). + * If <code>browseOnly</code> is <code>false</code>, the ClientConsumer will behave like consume the messages from the queue and + * the messages will effectively be removed from the queue. + * + * @param queueName name of the queue to consume messages from + * @param browseOnly whether the ClientConsumer will only browse the queue or consume messages. + * @return a ClientConsumer + * @throws HornetQException if an exception occurs while creating the ClientConsumer + */ ClientConsumer createConsumer(SimpleString queueName, boolean browseOnly) throws HornetQException; + /** + * Create a ClientConsumer to consume or browse messages from the queue with the given name. + * If <code>browseOnly</code> is <code>true</code>, the ClientConsumer will receive the messages from the queue + * but they will not be consumed (the messages will remain in the queue). + * If <code>browseOnly</code> is <code>false</code>, the ClientConsumer will behave like consume the messages from the queue and + * the messages will effectively be removed from the queue. + * + * @param queueName name of the queue to consume messages from + * @param browseOnly whether the ClientConsumer will only browse the queue or consume messages. + * @return a ClientConsumer + * @throws HornetQException if an exception occurs while creating the ClientConsumer + */ + ClientConsumer createConsumer(String queueName, boolean browseOnly) throws HornetQException; + + /** + * Create a ClientConsumer to consume or browse messages matching the filter from the queue with the given name. + * If <code>browseOnly</code> is <code>true</code>, the ClientConsumer will receive the messages from the queue + * but they will not be consumed (the messages will remain in the queue). + * If <code>browseOnly</code> is <code>false</code>, the ClientConsumer will behave like consume the messages from the queue and + * the messages will effectively be removed from the queue. + * + * @param queueName name of the queue to consume messages from + * @param filter only messages which match this filter will be consumed + * @param browseOnly whether the ClientConsumer will only browse the queue or consume messages. + * @return a ClientConsumer + * @throws HornetQException if an exception occurs while creating the ClientConsumer + */ + ClientConsumer createConsumer(String queueName, String filter, boolean browseOnly) throws HornetQException; + + /** + * Create a ClientConsumer to consume or browse messages matching the filter from the queue with the given name. + * If <code>browseOnly</code> is <code>true</code>, the ClientConsumer will receive the messages from the queue + * but they will not be consumed (the messages will remain in the queue). + * If <code>browseOnly</code> is <code>false</code>, the ClientConsumer will behave like consume the messages from the queue and + * the messages will effectively be removed from the queue. + * + * @param queueName name of the queue to consume messages from + * @param filter only messages which match this filter will be consumed + * @param browseOnly whether the ClientConsumer will only browse the queue or consume messages. + * @return a ClientConsumer + * @throws HornetQException if an exception occurs while creating the ClientConsumer + */ + ClientConsumer createConsumer(SimpleString queueName, SimpleString filterString, boolean browseOnly) throws HornetQException; + + /** + * Create a ClientConsumer to consume or browse messages matching the filter from the queue with the given name. + * If <code>browseOnly</code> is <code>true</code>, the ClientConsumer will receive the messages from the queue + * but they will not be consumed (the messages will remain in the queue). + * If <code>browseOnly</code> is <code>false</code>, the ClientConsumer will behave like consume the messages from the queue and + * the messages will effectively be removed from the queue. + * + * @param queueName name of the queue to consume messages from + * @param filter only messages which match this filter will be consumed + * @param windowSize the consumer window size + * @param maxRate the maximum rate to consume messages + * @param browseOnly whether the ClientConsumer will only browse the queue or consume messages. + * @return a ClientConsumer + * @throws HornetQException if an exception occurs while creating the ClientConsumer + */ ClientConsumer createConsumer(SimpleString queueName, - SimpleString filterString, + SimpleString filter, int windowSize, int maxRate, boolean browseOnly) throws HornetQException; - ClientConsumer createConsumer(String queueName) throws HornetQException; + /** + * Create a ClientConsumer to consume or browse messages matching the filter from the queue with the given name. + * If <code>browseOnly</code> is <code>true</code>, the ClientConsumer will receive the messages from the queue + * but they will not be consumed (the messages will remain in the queue). + * If <code>browseOnly</code> is <code>false</code>, the ClientConsumer will behave like consume the messages from the queue and + * the messages will effectively be removed from the queue. + * + * @param queueName name of the queue to consume messages from + * @param filter only messages which match this filter will be consumed + * @param windowSize the consumer window size + * @param maxRate the maximum rate to consume messages + * @param browseOnly whether the ClientConsumer will only browse the queue or consume messages. + * @return a ClientConsumer + * @throws HornetQException if an exception occurs while creating the ClientConsumer + */ + ClientConsumer createConsumer(String queueName, String filter, int windowSize, int maxRate, boolean browseOnly) throws HornetQException; - ClientConsumer createConsumer(String queueName, String filterString) throws HornetQException; + // Producer Operations ------------------------------------------- - ClientConsumer createConsumer(String queueName, String filterString, boolean browseOnly) throws HornetQException; - - ClientConsumer createConsumer(String queueName, boolean browseOnly) throws HornetQException; - - ClientConsumer createConsumer(String queueName, String filterString, int windowSize, int maxRate, boolean browseOnly) throws HornetQException; - /** * Create a producer with no default address. * Address must be specified every time a message is sent * + * @return a ClientProducer + * * @see ClientProducer#send(SimpleString, org.hornetq.core.message.Message) */ ClientProducer createProducer() throws HornetQException; + /** + * Create a produce which sends messages to the given address + * + * @param address the address to send messages to + * @return a ClientProducer + * @throws HornetQException if an exception occurs while creating the ClientProducer + */ ClientProducer createProducer(SimpleString address) throws HornetQException; + /** + * Create a produce which sends messages to the given address + * + * @param address the address to send messages to + * @return a ClientProducer + * @throws HornetQException if an exception occurs while creating the ClientProducer + */ + ClientProducer createProducer(String address) throws HornetQException; + + /** + * Create a produce which sends messages to the given address + * + * @param address the address to send messages to + * @param rate the producer rate + * @return a ClientProducer + * @throws HornetQException if an exception occurs while creating the ClientProducer + */ ClientProducer createProducer(SimpleString address, int rate) throws HornetQException; + /** + * Create a produce which sends messages to the given address + * + * @param address the address to send messages to + * @param rate the producer rate + * @return a ClientProducer + * @throws HornetQException if an exception occurs while creating the ClientProducer + */ + ClientProducer createProducer(String address, int rate) throws HornetQException; + + /** + * Create a produce which sends messages to the given address + * + * @param address the address to send messages to + * @param rate the producer rate + * @param blockOnNonPersistentSend whether to block when sending <em>non-persistent</em> messages or not + * @param blockOnPersistentSend whether to block when sending <em>persistent</em> messages or not + * @return a ClientProducer + * @throws HornetQException if an exception occurs while creating the ClientProducer + */ ClientProducer createProducer(SimpleString address, int maxRate, boolean blockOnNonPersistentSend, boolean blockOnPersistentSend) throws HornetQException; - ClientProducer createProducer(String address) throws HornetQException; - - ClientProducer createProducer(String address, int rate) throws HornetQException; - + /** + * Create a produce which sends messages to the given address + * + * @param address the address to send messages to + * @param rate the producer rate + * @param blockOnNonPersistentSend whether to block when sending <em>non-persistent</em> messages or not + * @param blockOnPersistentSend whether to block when sending <em>persistent</em> messages or not + * @return a ClientProducer + * @throws HornetQException if an exception occurs while creating the ClientProducer + */ ClientProducer createProducer(String address, int maxRate, boolean blockOnNonPersistentSend, boolean blockOnPersistentSend) throws HornetQException; - SessionQueueQueryResponseMessage queueQuery(SimpleString queueName) throws HornetQException; + // Message operations -------------------------------------------- - SessionBindingQueryResponseMessage bindingQuery(SimpleString address) throws HornetQException; + /** + * Create a ClientMessage. + * + * @param durable whether the created message is durable or not + * @return a ClientMessage + */ + ClientMessage createClientMessage(boolean durable); - XAResource getXAResource(); + /** + * Create a ClientMessage. + * + * @param type type of the message + * @param durable whether the created message is durable or not + * @return a ClientMessage + */ + ClientMessage createClientMessage(byte type, boolean durable); - boolean isRollbackOnly(); + /** + * Create a ClientMessage with the given HornetQBuffer as its body. + * + * @param durable whether the created message is durable or not + * @param buffer a HornetQBuffer which will be used as the messages's body + * @return a ClientMessage + */ + ClientMessage createClientMessage(boolean durable, HornetQBuffer buffer); - void commit() throws HornetQException; + /** + * Create a ClientMessage with the given HornetQBuffer as its body. + * + * @param durable whether the created message is durable or not + * @param expiration the message expiration + * @param timestamp the message timestamp + * @param priority the message priority (between 0 and 9 inclusive) + * @return a ClientMessage + */ + ClientMessage createClientMessage(byte type, boolean durable, long expiration, long timestamp, byte priority); - void rollback() throws HornetQException; + /** + * Create a HornetQBuffer containing the given bytes. + * + * @param bytes the buffer will be filled with these bytes + * @return a HornetQBuffer containing the given bytes + */ + HornetQBuffer createBuffer(byte[] bytes); /** - * @param considerLastMessageAsDelivered the first message on deliveringMessage Buffer is considered as delivered - * @throws HornetQException + * Create a HornetQBuffer of the given size. + * + * @param size size of the buffer to create + * @return a HornetQBuffer */ - void rollback(boolean considerLastMessageAsDelivered) throws HornetQException; + HornetQBuffer createBuffer(int size); - void close() throws HornetQException; + // Query operations ---------------------------------------------- - boolean isClosed(); + SessionQueueQueryResponseMessage queueQuery(SimpleString queueName) throws HornetQException; - boolean isAutoCommitSends(); + SessionBindingQueryResponseMessage bindingQuery(SimpleString address) throws HornetQException; - boolean isAutoCommitAcks(); + // Transaction operations ---------------------------------------- - boolean isBlockOnAcknowledge(); + /** + * Returns the XAResource associated to the session. + * + * @return the XAResource associated to the session + */ + XAResource getXAResource(); + /** + * Return <code>true</code> if the session supports XA, <code>false</code> else. + * + * @return <code>true</code> if the session supports XA, <code>false</code> else. + */ boolean isXA(); - ClientMessage createClientMessage(byte type, boolean durable, long expiration, long timestamp, byte priority); - ClientMessage createClientMessage(byte type, boolean durable); + /** + * Commit the current transaction. + * + * @throws HornetQException if an exception occurs while committing the transaction + */ + void commit() throws HornetQException; - ClientMessage createClientMessage(boolean durable); + /** + * Rollback the current transaction. + * + * @throws HornetQException if an exception occurs while rolling back the transaction + */ + void rollback() throws HornetQException; - ClientMessage createClientMessage(boolean durable, HornetQBuffer buffer); + /** + * Rollback the current transaction. + * + * @param considerLastMessageAsDelivered the first message on deliveringMessage Buffer is considered as delivered + * + * @throws HornetQException if an exception occurs while rolling back the transaction + */ + void rollback(boolean considerLastMessageAsDelivered) throws HornetQException; - HornetQBuffer createBuffer(byte[] bytes); + /** + * Return <code>true</code> if the current transaction has been flagged to rollback, <code>false</code> else. + * + * @return <code>true</code> if the current transaction has been flagged to rollback, <code>false</code> else. + */ + boolean isRollbackOnly(); - HornetQBuffer createBuffer(int size); + /** + * Return whether the session will <em>automatically</em> commit its transaction every time a message is sent + * by a ClientProducer created by this session, <code>false</code> else + * + * @return <code>true</code> if the session <em>automatically</em> commit its transaction every time a message is sent, <code>false</code> else + */ + boolean isAutoCommitSends(); - void start() throws HornetQException; + /** + * Return whether the session will <em>automatically</em> commit its transaction every time a message is acknowledged + * by a ClientConsumer created by this session, <code>false</code> else + * + * @return <code>true</code> if the session <em>automatically</em> commit its transaction every time a message is acknowledged, <code>false</code> else + */ + boolean isAutoCommitAcks(); - void stop() throws HornetQException; + /** + * Return whether the ClientConsumer created by the session will <em>block</em> when they acknowledge a message. + * + * @return <code>true</code> if the session's ClientConsumer block when they acknowledge a message, <code>false</code> else + */ + boolean isBlockOnAcknowledge(); - void addFailureListener(SessionFailureListener listener); + void setSendAcknowledgementHandler(SendAcknowledgementHandler handler); - boolean removeFailureListener(SessionFailureListener listener); - - int getVersion(); - - void setSendAcknowledgementHandler(SendAcknowledgementHandler handler); }