From 082815b1634d67ae0bbf356025b9e451da0dbdcc Mon Sep 17 00:00:00 2001
From: Arnaud Simon <arnaudsimon@apache.org>
Date: Thu, 16 Aug 2007 08:16:19 +0000
Subject: updated javadoc

git-svn-id: https://svn.apache.org/repos/asf/incubator/qpid/trunk/qpid@566538 13f79535-47bb-0310-9956-ffa450edef68
---
 .../java/org/apache/qpidity/client/Session.java    | 349 +++++++++++++--------
 1 file changed, 218 insertions(+), 131 deletions(-)

(limited to 'java/client')

diff --git a/java/client/src/main/java/org/apache/qpidity/client/Session.java b/java/client/src/main/java/org/apache/qpidity/client/Session.java
index dea6a01da6..1de6ce7aaa 100644
--- a/java/client/src/main/java/org/apache/qpidity/client/Session.java
+++ b/java/client/src/main/java/org/apache/qpidity/client/Session.java
@@ -31,11 +31,16 @@ import org.apache.qpidity.api.Message;
  * <p>A session is associated with a connection.
  * When created a Session is not attached with an underlying channel.
  * Session is single threaded </p>
+ * <p/>
+ * All the Session commands are asynchronous, synchronous invocation is achieved through invoking the sync method.
+ * That is to say that <code>command1</code> will be synchronously invoked using the following sequence:
+ * <ul>
+ * <li> <code>session.command1()</code>
+ * <li> <code>session.sync()</code>
+ * </ul>
  */
 public interface Session
 {
-    public static final short ACQUIRE_ANY_AVAILABLE_MESSAGE = 0;
-    public static final short ACQUIRE_MESSAGES_IF_ALL_ARE_AVAILABLE = 0;
     public static final short TRANSFER_ACQUIRE_MODE_NO_ACQUIRE = 0;
     public static final short TRANSFER_ACQUIRE_MODE_PRE_ACQUIRE = 1;
     public static final short TRANSFER_CONFIRM_MODE_REQUIRED = 1;
@@ -44,17 +49,21 @@ public interface Session
     public static final short MESSAGE_FLOW_MODE_WINDOW = 1;
     public static final short MESSAGE_FLOW_UNIT_MESSAGE = 0;
     public static final short MESSAGE_FLOW_UNIT_BYTE = 1;
+    public static final short MESSAGE_REJECT_CODE_GENERIC = 0;
+    public static final short MESSAGE_REJECT_CODE_IMMEDIATE_DELIVERY_FAILED = 1;
+    public static final short MESSAGE_ACQUIRE_ANY_AVAILABLE_MESSAGE = 0;
+    public static final short MESSAGE_ACQUIRE_MESSAGES_IF_ALL_ARE_AVAILABLE = 1;
 
     //------------------------------------------------------
     //                 Session housekeeping methods
     //------------------------------------------------------
-    
+
     /**
      * Sync method will block until all outstanding commands
      * are executed.
      */
     public void sync();
-    
+
     /**
      * Close this session and any associated resources.
      */
@@ -73,93 +82,109 @@ public interface Session
     //------------------------------------------------------
     /**
      * Transfer the given message to a specified exchange.
-     * 
+     * <p/>
      * <p>This is a convinience method for providing a complete message
      * using a single method which internaly is mapped to messageTransfer(), headers() followed
-     * by data() and an endData(). 
+     * by data() and an endData().
      * <b><i>This method should only be used by small messages</b></i></p>
      *
      * @param destination The exchange the message is being sent.
      * @param msg         The Message to be sent
-     * @param confirmMode <ul> </li>off (0): confirmation is not required, once a message has been transferred in pre-acquire
+     * @param confirmMode <ul> </li>off ({@link Session#TRANSFER_CONFIRM_MODE_NOT_REQUIRED}): confirmation
+     *                    is not required, once a message has been transferred in pre-acquire
      *                    mode (or once acquire has been sent in no-acquire mode) the message is considered
      *                    transferred
      *                    <p/>
-     *                    <li> on  (1): an acquired message (whether acquisition was implicit as in pre-acquire mode or
+     *                    <li> on  ({@link Session#TRANSFER_CONFIRM_MODE_REQUIRED}): an acquired message
+     *                    (whether acquisition was implicit as in pre-acquire mode or
      *                    explicit as in no-acquire mode) is not considered transferred until the original
      *                    transfer is complete (signaled via execution.complete)
      *                    </ul>
-     * @param acquireMode <ul> 
-     *                    <li> no-acquire  (0): the message must be explicitly acquired                    
-     *                    <li> pre-acquire (1): the message is acquired when the transfer starts
-     *                    </ul>                         
+     * @param acquireMode <ul>
+     *                    <li> no-acquire  ({@link Session#TRANSFER_ACQUIRE_MODE_NO_ACQUIRE}): the message
+     *                    must be explicitly acquired
+     *                    <li> pre-acquire ({@link Session#TRANSFER_ACQUIRE_MODE_PRE_ACQUIRE}): the message is
+     *                    acquired when the transfer starts
+     *                    </ul>
+     * @throws java.io.IOException If transferring a message fails due to some internal communication error.
      */
-    public void messageTransfer(String destination, Message msg, short confirmMode, short acquireMode)throws IOException;
-    
+    public void messageTransfer(String destination, Message msg, short confirmMode, short acquireMode)
+            throws IOException;
+
     /**
      * <p>This is a convinience method for streaming a message using pull semantics
      * using a single method as opposed to doing a push using messageTransfer(), headers() followed
-     * by a series of data() and an endData().</p> 
+     * by a series of data() and an endData().</p>
      * <p>Internally data will be pulled from Message object(which wrap's a data stream) using it's read()
      * and pushed using messageTransfer(), headers() followed by a series of data() and an endData().
      * <br><b><i>This method should only be used by large messages</b></i><br>
      * There are two convinience Message classes provided to facilitate this.
      * <ul>
-     * <li> <code>FileMessage</code>
-     * <li> <code>StreamingMessage</code>
+     * <li> <code>{@link org.apache.qpidity.client.util.FileMessage}</code>
+     * <li> <code>{@link org.apache.qpidity.client.util.StreamingMessage}</code>
      * </ul>
      * You could also implement a the <code>Message</code> interface to and wrap any
      * data stream you want.
      * </p>
-     * 
+     *
      * @param destination The exchange the message is being sent.
-     * @param msg         The Message to be sent  
-     * @param confirmMode <ul> </li>off (0): confirmation is not required, once a message has been transferred in pre-acquire
+     * @param msg         The Message to be sent
+     * @param confirmMode <ul> </li>off ({@link Session#TRANSFER_CONFIRM_MODE_NOT_REQUIRED}): confirmation
+     *                    is not required, once a message has been transferred in pre-acquire
      *                    mode (or once acquire has been sent in no-acquire mode) the message is considered
      *                    transferred
      *                    <p/>
-     *                    <li> on  (1): an acquired message (whether acquisition was implicit as in pre-acquire mode or
+     *                    <li> on  ({@link Session#TRANSFER_CONFIRM_MODE_REQUIRED}): an acquired message
+     *                    (whether acquisition was implicit as in pre-acquire mode or
      *                    explicit as in no-acquire mode) is not considered transferred until the original
      *                    transfer is complete (signaled via execution.complete)
      *                    </ul>
-     * @param acquireMode <ul> <li> no-acquire  (0): the message must be explicitly acquired
-     *                    <p/>
-     *                    <li> pre-acquire (1): the message is acquired when the transfer starts
+     * @param acquireMode <ul>
+     *                    <li> no-acquire  ({@link Session#TRANSFER_ACQUIRE_MODE_NO_ACQUIRE}): the message
+     *                    must be explicitly acquired
+     *                    <li> pre-acquire ({@link Session#TRANSFER_ACQUIRE_MODE_PRE_ACQUIRE}): the message
+     *                    is acquired when the transfer starts
      *                    </ul>
+     * @throws java.io.IOException If transferring a message fails due to some internal communication error.
      */
-    public void messageStream(String destination, Message msg, short confirmMode, short acquireMode)throws IOException;
+    public void messageStream(String destination, Message msg, short confirmMode, short acquireMode) throws IOException;
 
     /**
      * Declare the beginning of a message transfer operation. This operation must
-     * be followed by {@link Session#addMessageHeaders} then followed by any number of {@link Session#addData}.
-     * The transfer is ended by endData.
+     * be followed by {@link Session#headers} then followed by any number of {@link Session#data}.
+     * The transfer is ended by {@link Session#endData}.
      * <p> This way of transferring messages is useful when streaming large messages
      * <p> In the interval [messageTransfer endData] any attempt to call a method other than
-     * {@link Session#addMessageHeaders}, {@link Session#endData} ore {@link Session#close}
+     * {@link Session#headers}, {@link Session#endData} ore {@link Session#sessionClose}
      * will result in an exception being thrown.
      *
-     * @param confirmMode <ul> </li>off (0): confirmation is not required, once a message has been transferred in pre-acquire
+     * @param destination The exchange the message is being sent.
+     * @param confirmMode <ul> </li>off ({@link Session#TRANSFER_CONFIRM_MODE_NOT_REQUIRED}): confirmation
+     *                    is not required, once a message has been transferred in pre-acquire
      *                    mode (or once acquire has been sent in no-acquire mode) the message is considered
      *                    transferred
      *                    <p/>
-     *                    <li> on  (1): an acquired message (whether acquisition was implicit as in pre-acquire mode or
+     *                    <li> on  ({@link Session#TRANSFER_CONFIRM_MODE_REQUIRED}): an acquired message
+     *                    (whether acquisition was implicit as in pre-acquire mode or
      *                    explicit as in no-acquire mode) is not considered transferred until the original
      *                    transfer is complete (signaled via execution.complete)
      *                    </ul>
-     * @param acquireMode <ul> <li> no-acquire  (0): the message must be explicitly acquired
-     *                    <p/>
-     *                    <li> pre-acquire (1): the message is acquired when the transfer starts
+     * @param acquireMode <ul>
+     *                    <li> no-acquire  ({@link Session#TRANSFER_ACQUIRE_MODE_NO_ACQUIRE}): the message
+     *                    must be explicitly acquired
+     *                    <li> pre-acquire ({@link Session#TRANSFER_ACQUIRE_MODE_PRE_ACQUIRE}): the message
+     *                    is acquired when the transfer starts
      *                    </ul>
-     * @param exchange    The exchange the message is being sent.
      */
     public void messageTransfer(String destination, short confirmMode, short acquireMode);
 
     /**
-     * Add the following headers ( {@link org.apache.qpidity.DeliveryProperties}
-     * or to the message being sent.
+     * Add a set of headers the following headers to the message being sent.
      *
-     * @param headers are Either <code>DeliveryProperties</code> or <code>ApplicationProperties</code>
+     * @param headers Are either <code>{@link org.apache.qpidity.DeliveryProperties}</code>
+     *                or <code>{@link org.apache.qpidity.MessageProperties}</code>
      * @see org.apache.qpidity.DeliveryProperties
+     * @see org.apache.qpidity.MessageProperties
      */
     public void headers(Struct... headers);
 
@@ -169,21 +194,24 @@ public interface Session
      * @param data Data to be added.
      */
     public void data(byte[] data);
-    
+
     /**
      * Add the following ByteBuffer to the content of the message being sent.
+     * <p> Note that only the data between the buffer current position and the
+     * buffer limit is added.
+     * It is therefore recommended to flip the buffer before adding it to the message,
      *
-     * @param data Data to be added.
-     */    
+     * @param buf Data to be added.
+     */
     public void data(ByteBuffer buf);
 
     /**
      * Add the following String to the content of the message being sent.
      *
-     * @param data Data to be added.
-     */    
+     * @param str String to be added.
+     */
     public void data(String str);
-    
+
     /**
      * Signals the end of data for the message.
      */
@@ -198,35 +226,38 @@ public interface Session
      * Associate a message listener with a destination.
      * <p> The destination is bound to a queue and messages are filtered based
      * on the provider filter map (message filtering is specific to the provider and may not be handled).
-     * <p/>
-     * <p> Following are the valid options
+     * <p> Following are valid options:
      * <ul>
-     * <li> NO_LOCAL
-     * <li> EXCLUSIVE
-     * </ul>
-     * <p> In the absence of a particular option, defaul values are:
-     * <ul>
-     * <li> NO_LOCAL = false
-     * <li> EXCLUSIVE = false
+     * <li>{@link Option#NO_LOCAL}: <p>If the no-local field is set the server will not send
+     * messages to the connection that
+     * published them.
+     * <li>{@link Option#EXCLUSIVE}: <p> Request exclusive subscription access, meaning only this
+     * ubscription can access the queue.
+     * <li>{@link Option#NO_OPTION}: <p> Has no effect as it represents an “empty” option.
      * </ul>
      *
      * @param queue       The queue this receiver is receiving messages from.
      * @param destination The destination for the subscriber ,a.k.a the delivery tag.
-     * @param confirmMode <ul> </li>off (0): confirmation is not required, once a message has been transferred in pre-acquire
+     * @param confirmMode <ul> </li>off ({@link Session#TRANSFER_CONFIRM_MODE_NOT_REQUIRED}): confirmation is not
+     *                    required, once a message has been transferred in pre-acquire
      *                    mode (or once acquire has been sent in no-acquire mode) the message is considered
      *                    transferred
      *                    <p/>
-     *                    <li> on  (1): an acquired message (whether acquisition was implicit as in pre-acquire mode or
+     *                    <li> on  ({@link Session#TRANSFER_CONFIRM_MODE_REQUIRED}): an acquired message (whether
+     *                    acquisition was implicit as in pre-acquire mode or
      *                    explicit as in no-acquire mode) is not considered transferred until the original
      *                    transfer is complete (signaled via execution.complete)
      *                    </ul>
-     * @param acquireMode <ul> <li> no-acquire  (0): the message must be explicitly acquired
-     *                    <p/>
-     *                    <li> pre-acquire (1): the message is acquired when the transfer starts
+     * @param acquireMode <ul>
+     *                    <li> no-acquire  ({@link Session#TRANSFER_ACQUIRE_MODE_NO_ACQUIRE}): the message must
+     *                    be explicitly acquired
+     *                    <li> pre-acquire ({@link Session#TRANSFER_ACQUIRE_MODE_PRE_ACQUIRE}): the message is
+     *                    acquired when the transfer starts
      *                    </ul>
      * @param listener    The listener for this destination. When big message are transfered then
      *                    it is recommended to use a {@link org.apache.qpidity.client.MessagePartListener}.
-     * @param options     Set of Options.
+     * @param options     Set of Options (valid options are {@link Option#NO_LOCAL}, {@link Option#EXCLUSIVE}
+     *                    and {@link Option#NO_OPTION})
      * @param filter      A set of filters for the subscription. The syntax and semantics of these filters depends
      *                    on the providers implementation.
      */
@@ -245,12 +276,10 @@ public interface Session
 
     /**
      * Associate a message part listener with a destination.
-     * We currently allow one listerner per destination this means
+     * <p> Only one listerner per destination is allowed. This means
      * that the previous message listener is replaced. This is done gracefully i.e. the message
      * listener is replaced once it return from the processing of a message.
      *
-     * // todo when a listener is null then received messages must be released 
-     *
      * @param destination The destination the listener is associated with.
      * @param listener    The new listener for this destination.
      */
@@ -258,20 +287,18 @@ public interface Session
 
     /**
      * Sets the mode of flow control used for a given destination.
-     * <p/>
-     * With credit based flow control, the broker continually maintains its current
+     * <p> With credit based flow control, the broker continually maintains its current
      * credit balance with the recipient. The credit balance consists of two values, a message
      * count, and a byte count. Whenever message data is sent, both counts must be decremented.
      * If either value reaches zero, the flow of message data must stop. Additional credit is
      * received via the {@link Session#messageFlow} method.
-     * <p/>
-     * Window based flow control is identical to credit based flow control, however message
+     * <p> Window based flow control is identical to credit based flow control, however message
      * acknowledgment implicitly grants a single unit of message credit, and the size of the
      * message in byte credits for each acknowledged message.
      *
      * @param destination The destination to set the flow mode on.
-     * @param mode        <ul> <li>credit (0): choose credit based flow control
-     *                    <li> window (1): choose window based flow control</ul>
+     * @param mode        <ul> <li>credit ({@link Session#MESSAGE_FLOW_MODE_CREDIT}): choose credit based flow control
+     *                    <li> window ({@link Session#MESSAGE_FLOW_MODE_WINDOW}): choose window based flow control</ul>
      */
     public void messageFlowMode(String destination, short mode);
 
@@ -289,8 +316,8 @@ public interface Session
      * @param unit        Specifies the unit of credit balance.
      *                    <p/>
      *                    One of: <ul>
-     *                    <li> message (0)
-     *                    <li> byte    (1)
+     *                    <li> message ({@link Session#MESSAGE_FLOW_UNIT_MESSAGE})
+     *                    <li> byte    ({@link Session#MESSAGE_FLOW_UNIT_BYTE})
      *                    </ul>
      * @param value       Number of credits, a value of 0 indicates an infinite amount of credit.
      */
@@ -300,7 +327,7 @@ public interface Session
      * Forces the broker to exhaust its credit supply.
      * <p> The broker's credit will always be zero when
      * this method completes. This method does not complete until all the message transfers occur.
-     * <p> This method returns the number of flushed messages. 
+     * <p> This method returns the number of flushed messages.
      *
      * @param destination The destination to call flush on.
      */
@@ -327,17 +354,31 @@ public interface Session
 
     /**
      * Reject ranges of acquired messages.
-     * <p> A rejected message will not be delivered to any receiver
-     * and may be either discarded or moved to the broker dead letter queue.
+     * <p>  The broker MUST deliver rejected messages to the
+     * alternate-exchange on the queue from which it was delivered. If no alternate-exchange is
+     * defined for that queue the broker MAY discard the message.
      *
      * @param ranges Range of rejected messages.
-     * @param code TODO
-     * @param text TODO
+     * @param code   The reject code must be one of {@link Session#MESSAGE_REJECT_CODE_GENERIC} or
+     *               {@link Session#MESSAGE_REJECT_CODE_IMMEDIATE_DELIVERY_FAILED} (immediate delivery was attempted but
+     *               failed).
+     * @param text   String describing the reason for a message transfer rejection.
      */
     public void messageReject(RangeSet ranges, int code, String text);
-    
-    /** 
-     * @return the rejected message ranges
+
+    /**
+     * As it is possible that the broker does not manage to reject some messages, after completion of
+     * {@link Session#messageReject} this method will return the ranges of rejected messages.
+     * <p> Note that {@link Session#messageReject} and this methods are asynchronous therefore for accessing to the
+     * previously rejected messages this method must be invoked in conjunction with {@link Session#sync()}.
+     * <p> A recommended invocation sequence would be:
+     * <ul>
+     * <li> {@link Session#messageReject}
+     * <li> {@link Session#sync()}
+     * <li> {@link Session#getRejectedMessages()}
+     * </ul>
+     *
+     * @return The rejected message ranges
      */
     public RangeSet getRejectedMessages();
 
@@ -348,21 +389,38 @@ public interface Session
      * message acquisition can fail.
      * The outcome of the acquisition is returned as an array of ranges of qcquired messages.
      * <p> This method should only be called on non-acquired messages.
-     * @param mode TODO
-     * @param range Ranges of messages to be acquired.
+     *
+     * @param mode   One of: <ul>
+     *               <li> any ({@link Session#MESSAGE_ACQUIRE_ANY_AVAILABLE_MESSAGE}): acquire any available
+     *               messages for consumption
+     *               <li> all ({@link Session#MESSAGE_ACQUIRE_MESSAGES_IF_ALL_ARE_AVAILABLE}): only acquire messages
+     *               if all are available for consumption
+     *               </ul>
+     * @param ranges Ranges of messages to be acquired.
      */
     public void messageAcquire(RangeSet ranges, short mode);
 
-    /** 
+    /**
+     * As it is possible that the broker does not manage to acquire some messages, after completion of
+     * {@link Session#messageAcquire} this method will return the ranges of acquired messages.
+     * <p> Note that {@link Session#messageAcquire} and this methods are asynchronous therefore for accessing to the
+     * previously acquired messages this method must be invoked in conjunction with {@link Session#sync()}.
+     * <p> A recommended invocation sequence would be:
+     * <ul>
+     * <li> {@link Session#messageAcquire}
+     * <li> {@link Session#sync()}
+     * <li> {@link Session#getAccquiredMessages()}
+     * </ul>
+     *
      * @return returns the message ranges marked by the broker as acquired.
      */
     public RangeSet getAccquiredMessages();
-    
+
     /**
      * Give up responsibility for processing ranges of messages.
      * <p> Released messages are re-enqueued.
      *
-     * @param range Ranges of messages to be released.
+     * @param ranges Ranges of messages to be released.
      */
     public void messageRelease(RangeSet ranges);
 
@@ -376,12 +434,14 @@ public interface Session
 
     /**
      * Commit the receipt and the delivery of all messages exchanged by this session resources.
+     *
      * @throws IllegalStateException If this session is not transacted.
      */
     public void txCommit() throws IllegalStateException;
 
     /**
      * Rollback the receipt and the delivery of all messages exchanged by this session resources.
+     *
      * @throws IllegalStateException If this session is not transacted.
      */
     public void txRollback() throws IllegalStateException;
@@ -392,26 +452,36 @@ public interface Session
 
     /**
      * Declare a queue with the given queueName
-     * <p> Following are the valid options for declareQueue
+     * <p> Following are the valid options:
      * <ul>
-     * <li> AUTO_DELETE
-     * <li> DURABLE
-     * <li> EXCLUSIVE
-     * <li> NO_WAIT
-     * <li> PASSIVE
+     * <li> {@link Option#AUTO_DELETE}: <p> If this field is set and the exclusive field is also set,
+     * then the queue is deleted when the connection closes.
+     * If this field is set and the exclusive field is not set the queue is deleted when all
+     * the consumers have finished using it.
+     * <li> {@link Option#DURABLE}: <p>  If set when creating a new queue,
+     * the queue will be marked as durable. Durable queues
+     * remain active when a server restarts. Non-durable queues (transient queues) are purged
+     * if/when a server restarts. Note that durable queues do not necessarily hold persistent
+     * messages, although it does not make sense to send persistent messages to a transient
+     * queue.
+     * <li> {@link Option#EXCLUSIVE}: <p>  Exclusive queues can only be used from one connection at a time.
+     * Once a connection declares an exclusive queue, that queue cannot be used by any other connections until the
+     * declaring connection closes.
+     * <li> {@link Option#PASSIVE}: <p> If set, the server will not create the queue.
+     * This field allows the client to assert the presence of a queue without modifying the server state.
+     * <li>{@link Option#NO_OPTION}: <p> Has no effect as it represents an “empty” option.
      * </ul>
-     * </p>
-     * <p/>
      * <p>In the absence of a particular option, the defaul value is false for each option
      *
      * @param queueName         The name of the delcared queue.
      * @param alternateExchange If a message is rejected by a queue, then it is sent to the alternate-exchange. A message
      *                          may be rejected by a queue for the following reasons:
      *                          <oL> <li> The queue is deleted when it is not empty;
-     *                          <<li> Immediate delivery of a message is requested, but there are no consumers connected to
+     *                          <li> Immediate delivery of a message is requested, but there are no consumers connected to
      *                          the queue. </ol>
      * @param arguments         Used for backward compatibility
-     * @param options           Set of Options.
+     * @param options           Set of Options ( valide options are: {@link Option#AUTO_DELETE}, {@link Option#DURABLE},
+     *                          {@link Option#EXCLUSIVE}, {@link Option#PASSIVE} and  {@link Option#NO_OPTION})
      * @see Option
      */
     public void queueDeclare(String queueName, String alternateExchange, Map<String, ?> arguments, Option... options);
@@ -419,9 +489,16 @@ public interface Session
     /**
      * Bind a queue with an exchange.
      *
-     * @param queueName    The queue to be bound.
+     * @param queueName    Specifies the name of the queue to bind. If the queue name is empty, refers to the current
+     *                     queue for the session, which is the last declared queue.
      * @param exchangeName The exchange name.
-     * @param routingKey   The routing key.
+     * @param routingKey   Specifies the routing key for the binding. The routing key is used for routing messages
+     *                     depending on the exchange configuration. Not all exchanges use a routing key - refer to
+     *                     the specific exchange documentation. If the queue name is empty, the server uses the last
+     *                     queue declared on the session. If the routing key is also empty, the server uses this
+     *                     queue name for the routing key as well. If the queue name is provided but the routing key
+     *                     is empty, the server does the binding with that empty routing key. The meaning of empty
+     *                     routing keys depends on the exchange implementation.
      * @param arguments    Used for backward compatibility
      */
     public void queueBind(String queueName, String exchangeName, String routingKey, Map<String, ?> arguments);
@@ -429,37 +506,42 @@ public interface Session
     /**
      * Unbind a queue from an exchange.
      *
-     * @param queueName    The queue to be unbound.
-     * @param exchangeName The exchange name.
-     * @param routingKey   The routing key.
+     * @param queueName    Specifies the name of the queue to unbind.
+     * @param exchangeName The name of the exchange to unbind from.
+     * @param routingKey   Specifies the routing key of the binding to unbind.
      * @param arguments    Used for backward compatibility
      */
     public void queueUnbind(String queueName, String exchangeName, String routingKey, Map<String, ?> arguments);
 
     /**
-     * Purge a queue. i.e. delete all enqueued messages
+     * This method removes all messages from a queue. It does not cancel consumers. Purged messages
+     * are deleted without any formal "undo" mechanism.
      *
-     * @param queueName The queue to be purged
+     * @param queueName Specifies the name of the queue to purge. If the queue name is empty, refers to the
+     *                  current queue for the session, which is the last declared queue.
      */
     public void queuePurge(String queueName);
 
     /**
-     * Delet a queue.
-     * <p> Following are the valid options for createReceive
+     * This method deletes a queue. When a queue is deleted any pending messages are sent to a
+     * dead-letter queue if this is defined in the server configuration, and all consumers on the
+     * queue are cancelled.
+     * <p> Following are the valid options:
      * <ul>
-     * <li> IF_EMPTY
-     * <li> IF_UNUSE
-     * <li> NO_WAIT
+     * <li> {@link Option#IF_EMPTY}: <p>  If set, the server will only delete the queue if it has no messages.
+     * <li> {@link Option#IF_UNUSED}: <p> If set, the server will only delete the queue if it has no consumers.
+     * If the queue has consumers the server does does not delete it but raises a channel exception instead.
+     * <li>{@link Option#NO_OPTION}: <p> Has no effect as it represents an “empty” option.
      * </ul>
      * </p>
      * <p/>
      * <p>In the absence of a particular option, the defaul value is false for each option</p>
      *
-     * @param queueName The name of the queue to be deleted
-     * @param options   Set of options
+     * @param queueName Specifies the name of the queue to delete. If the queue name is empty, refers to the
+     *                  current queue for the session, which is the last declared queue.
+     * @param options   Set of options (Valid options are: {@link Option#IF_EMPTY}, {@link Option#IF_UNUSED}
+     *                  and {@link Option#NO_OPTION})
      * @see Option
-     *      <p/>
-     *      Following are the valid options
      */
     public void queueDelete(String queueName, Option... options);
 
@@ -468,48 +550,53 @@ public interface Session
     // --------------------------------------
 
     /**
-     * Declare an exchange.
-     * <p> Following are the valid options for createReceive
+     * This method creates an exchange if it does not already exist, and if the exchange exists,
+     * verifies that it is of the correct and expected class.
+     * <p> Following are the valid options:
      * <ul>
-     * <li> AUTO_DELETE
-     * <li> DURABLE
-     * <li> INTERNAL
-     * <li> NO_WAIT
-     * <li> PASSIVE
+     * <li> {@link Option#AUTO_DELETE}: <p> If set, the exchange is deleted when all queues have finished using it.
+     * <li> {@link Option#DURABLE}: <p> If set when creating a new exchange, the exchange will
+     * be marked as durable. Durable exchanges remain active when a server restarts. Non-durable exchanges (transient
+     * exchanges) are purged if/when a server restarts.
+     * <li> {@link Option#PASSIVE}: <p> If set, the server will not create the exchange.
+     * The client can use this to check whether an exchange exists without modifying the server state.
+     * <li> {@link Option#NO_OPTION}: <p> Has no effect as it represents an “empty” option.
      * </ul>
-     * </p>
-     * <p/>
-     * <p>In the absence of a particular option, the defaul value is false for each option</p>     *
+     * <p>In the absence of a particular option, the defaul value is false for each option</p>
      *
      * @param exchangeName      The exchange name.
-     * @param exchangeClass     The fully qualified name of the exchange class.
+     * @param type              Each exchange belongs to one of a set of exchange types implemented by the server. The
+     *                          exchange types define the functionality of the exchange - i.e. how messages are routed
+     *                          through it. It is not valid or meaningful to attempt to change the type of an existing
+     *                          exchange.
      * @param alternateExchange In the event that a message cannot be routed, this is the name of the exchange to which
      *                          the message will be sent.
-     * @param options           Set of options.
+     * @param options           Set of options (valid options are: {@link Option#AUTO_DELETE}, {@link Option#DURABLE},
+     *                          {@link Option#PASSIVE}, {@link Option#NO_OPTION})
      * @param arguments         Used for backward compatibility
      * @see Option
      */
-    public void exchangeDeclare(String exchangeName, String exchangeClass, String alternateExchange,
-                                Map<String, ?> arguments, Option... options);
+    public void exchangeDeclare(String exchangeName, String type, String alternateExchange, Map<String, ?> arguments,
+                                Option... options);
 
     /**
-     * Delete an exchange.
-     * <p> Following are the valid options for createReceive
+     * This method deletes an exchange. When an exchange is deleted all queue bindings on the
+     * exchange are cancelled.
+     * <p> Following are the valid options:
      * <ul>
-     * <li> IF_UNUSEDL
-     * <li> NO_WAIT
+     * <li> {@link Option#IF_UNUSED}: <p> If set, the server will only delete the exchange if it has no queue bindings. If the
+     * exchange has queue bindings the server does not delete it but raises a channel exception
+     * instead.
+     * <li> {@link Option#NO_OPTION}: <p> Has no effect as it represents an “empty” option.
      * </ul>
-     * </p>
-     * <p/>
      * <p>In the absence of a particular option, the defaul value is false for each option
-     * Immediately deleted even if it is used by another resources.</p>
      *
      * @param exchangeName The name of exchange to be deleted.
-     * @param options      Set of options.
+     * @param options      Set of options (valid options are:  {@link Option#IF_UNUSED}, {@link Option#NO_OPTION})
      * @see Option
      */
     public void exchangeDelete(String exchangeName, Option... options);
-    
+
     /**
      * If the session receives a sessionClosed with an error code it
      * informs the session's ExceptionListener
-- 
cgit v1.2.1