updated javadoc

git-svn-id: https://svn.apache.org/repos/asf/incubator/qpid/trunk/qpid@566538 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 218 insertions, 131 deletions

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