changed the session interface method names and signatures to match the methods generated in Rafi's invoker class. I also added java doc describing what options are valid for each method and their default values in the absence of a each option

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

1 files changed, 144 insertions, 63 deletions

diff --git a/java/client/src/main/java/org/apache/qpid/nclient/api/Session.java b/java/client/src/main/java/org/apache/qpid/nclient/api/Session.java
index dbe1b68e80..2a68297df4 100644
--- a/java/client/src/main/java/org/apache/qpid/nclient/api/Session.java
+++ b/java/client/src/main/java/org/apache/qpid/nclient/api/Session.java
@@ -19,6 +19,7 @@
 package org.apache.qpid.nclient.api;
 
 import org.apache.qpid.nclient.exception.QpidException;
+import org.apache.qpidity.Option;
 
 /**
  * A session is associated with a connection.
@@ -31,13 +32,22 @@ import org.apache.qpid.nclient.exception.QpidException;
  */
 public interface Session
 {
+	
+	/**
+	 * -------------------------------------
+	 * Session housekeeping methods
+	 * -------------------------------------
+	 */
+	
     /**
      * Close this session and any associated resources.
      *
      * @throws QpidException If the communication layer fails to close this session or if an internal error happens
      *                       when closing this session resources. .
      */
-    public void close() throws QpidException;
+    public void close()
+            throws
+            QpidException;
 
     /**
      * Suspend this session resulting in interrupting the traffic with the broker.
@@ -45,7 +55,9 @@ public interface Session
      *
      * @throws QpidException If the communication layer fails to suspend this session
      */
-    public void suspend() throws QpidException;
+    public void suspend()
+            throws
+            QpidException;
 
     /**
      * Unsuspended a Session is equivalent to attaching a communication channel that can be used to
@@ -54,15 +66,17 @@ public interface Session
      *
      * @throws QpidException If the communication layer fails to unsuspend this session
      */
-    public void unsuspend() throws QpidException;
+    public void unsuspend()
+            throws
+            QpidException;
 
+    
     /**
-     * Gives up responsibility to all messages that have not yet been delivered to MessageReceiver.
-     *
-     * @throws QpidException If the communication layer fails to release undelivered messages.
-     */
-    public void releaseUndeliveredMessages() throws QpidException;
-
+	 * -------------------------------------
+	 * Messaging methods
+	 * -------------------------------------
+	 */
+    
     /**
      * Create a message sender for sending messages to queue queueName.
      *
@@ -70,36 +84,59 @@ public interface Session
      * @return A sender for queue queueName
      * @throws QpidException If the session fails to create the sended due to some error
      */
-    public MessageSender createSender(String queueName) throws QpidException;
+    public MessageSender createSender(String queueName)
+            throws
+            QpidException;
     //Todo: Do we need to define more specific exception like queue name not valid?
 
     /**
      * Create a message receiver for receiving messages from queue queueName.
-     * <p> see available options: {@link CreateReceiverOption}
-     * <p> When non of the options are set then the receiver is created with:
+     * <p> Following are the valid options for createReceive
      * <ul>
-     * <li> no_local = false
-     * <li> non exclusive
-     * <li> pre-acquire mode
-     * <li> no confirmation
+     * <li> NO_LOCAL
+     * <li> EXCLUSIVE
+     * <li> NO_ACQUIRE
+     * <li> CONFIRM
      * </ul>
-     *
+     * </p>
+     * 
+     * <p> In the absence of a particular option, the defaul value is:  
+     * <ul>
+     * <li> NO_LOCAL = false
+     * <li> EXCLUSIVE = false
+     * <li> PRE-ACCQUIRE
+     * <li> CONFIRM = false
+     * </ul>
+     * </p>
+     * 
      * @param queueName The queue this receiver is receiving messages from.
      * @param options   Set of Options.
      * @return A receiver for queue queueName.
      * @throws QpidException If the session fails to create the receiver due to some error.
-     * @see CreateReceiverOption
+     * @see Option
      */
-    public MessageReceiver createReceiver(String queueName, CreateReceiverOption... options) throws QpidException;
+    public MessageReceiver createReceiver(String queueName, Option... options)
+            throws
+            QpidException;
     //Todo: Do we need to define more specific exceptions like queue name not valid?
 
+    
+    /**
+	 * -------------------------------------
+	 * Transaction methods
+	 * -------------------------------------
+	 */
+
     /**
      * Commit the receipt and the delivery of all messages exchanged by this session resources.
      *
      * @throws QpidException         If the session fails to commit due to some error.
      * @throws IllegalStateException If this session is not transacted.
      */
-    public void commit() throws QpidException, IllegalStateException;
+    public void commit()
+            throws
+            QpidException,
+            IllegalStateException;
 
     /**
      * Rollback the receipt and the delivery of all messages exchanged by this session resources.
@@ -107,35 +144,51 @@ public interface Session
      * @throws QpidException         If the session fails to rollback due to some error.
      * @throws IllegalStateException If this session is not transacted.
      */
-    public void rollback() throws QpidException, IllegalStateException;
+    public void rollback()
+            throws
+            QpidException,
+            IllegalStateException;
 
     /**
      * Set this session as transacted.
      * <p> This operation is irreversible.
      *
-     * @throws QpidException         If the session fail to be transacted due to some error.
+     * @throws QpidException         If the session fails to be transacted due to some error.
      * @throws IllegalStateException If this session is already transacted.
      */
-    public void setTransacted() throws QpidException, IllegalStateException;
+    public void setTransacted()
+            throws
+            QpidException,
+            IllegalStateException;
 
     /**
-     * Declare a queue of name queueName
-     * <p> see available options: {@link DeclareQueueOption}
-     * <p> When non of the options are set then the receiver is created with:
+	 * -------------------------------------
+	 * Queue methods
+	 * -------------------------------------
+	 */
+
+    /**
+     * Declare a queue with the given queueName
+     * <p> Following are the valid options for declareQueue
      * <ul>
-     * <li> auto_delete = false
-     * <li> non-durable
-     * <li> non-exccusive
-     * <li> nowait = false
-     * <li> not passive
+     * <li> AUTO_DELETE
+     * <li> DURABLE
+     * <li> EXCLUSIVE
+     * <li> NO_WAIT
+     * <li> PASSIVE
      * </ul>
-     *
+     * </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 options   Set of Options.
      * @throws QpidException If the session fails to declare the queue due to some error.
-     * @see DeclareQueueOption
+     * @see Option
      */
-    public void declareQueue(String queueName, DeclareQueueOption... options) throws QpidException;
+    public void queueDeclare(String queueName, Option... options)
+            throws
+            QpidException;
     //Todo: Do we need to define more specific exceptions like queue name already exist?
 
     /**
@@ -144,9 +197,12 @@ public interface Session
      * @param queueName    The queue to be bound.
      * @param exchangeName The exchange name.
      * @param routingKey   The routing key.
+     * @param nowait       nowait
      * @throws QpidException If the session fails to bind the queue due to some error.
      */
-    public void bindQueue(String queueName, String exchangeName, String routingKey) throws QpidException;
+    public void queueBind(String queueName, String exchangeName, String routingKey)
+            throws
+            QpidException;
     //Todo: Do we need to define more specific exceptions like exchange does not exist?
 
     /**
@@ -157,7 +213,9 @@ public interface Session
      * @param routingKey   The routing key.
      * @throws QpidException If the session fails to unbind the queue due to some error.
      */
-    public void unbindQueue(String queueName, String exchangeName, String routingKey) throws QpidException;
+    public void queueUnbind(String queueName, String exchangeName, String routingKey)
+            throws
+            QpidException;
     //Todo: Do we need to define more specific exceptions like exchange does not exist?
 
     /**
@@ -165,57 +223,80 @@ public interface Session
      * TODO: Define the exact semantic i.e. are message sent to a dead letter queue?
      *
      * @param queueName The queue to be purged
+     * @param nowait    nowait
      * @throws QpidException If the session fails to purge the queue due to some error.
      */
-    public void purgeQueue(String queueName) throws QpidException;
+    public void queuePurge(String queueName)
+            throws
+            QpidException;
 
     /**
      * Delet a queue.
-     * <p> see available options: {@link DeleteQueueOption}
-     * <p> When non of the options are set then The queue is immediately deleted even
-     * if it still contains messages or if ti is used by another resource.
+     * <p> Following are the valid options for createReceive
+     * <ul>
+     * <li> IF_EMPTY
+     * <li> IF_UNUSE
+     * <li> NO_WAIT
+     * </ul>
+     * </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
      * @throws QpidException If the session fails to delete the queue due to some error.
-     * @see DeleteQueueOption
+     * @see Option
+     * 
+     * Following are the valid options 
      */
-    public void deleteQueue(String queueName, DeleteQueueOption options) throws QpidException;
+    public void queueDelete(String queueName, Option options)
+            throws
+            QpidException;
 
     /**
      * Declare an exchange.
-     * <p> see available options: {@link DeclareExchangeOption}
-     * <p> When non of the options are set then the exchange is declared with:
+     * <p> Following are the valid options for createReceive
      * <ul>
-     * <li> auto_delete = false
-     * <li> non-durable
-     * <li> internal = false
-     * <li> nowait = false
-     * <li> not passive
+     * <li> AUTO_DELETE
+     * <li> DURABLE
+     * <li> INTERNAL
+     * <li> NO_WAIT
+     * <li> PASSIVE
      * </ul>
+     * </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 alternateExchange The alternate exchange.
-     * @param options           Set of options.
-     * @throws QpidException If the session fails to declare the exchange due to some error.
-     * @see DeclareExchangeOption
+     * @param exchangeName  The exchange name.
+     * @param exchangeClass The fully qualified name of the exchange class.
+     * @param options       Set of options.
+     * @throws QpidException  If the session fails to declare the exchange due to some error.
+     * @see Option
      */
-    public void declareExchange(String exchangeName, String exchangeClass, String alternateExchange,
-                                DeclareExchangeOption... options) throws QpidException;
+    public void exchangeDeclare(String exchangeName, String exchangeClass, String alternateExchange, Option... options)
+            throws
+            QpidException;
     //Todo: Do we need to define more specific exceptions like exchange already exist?
 
     /**
      * Delete an exchange.
-     * <p> see available options: {@link DeclareExchangeOption}
-     * <p> When non of the options are set then the exchange
-     * Immediately deleted even if it is used by another resources.
+     * <p> Following are the valid options for createReceive
+     * <ul>
+     * <li> IF_UNUSEDL
+     * <li> NO_WAIT
+     * </ul>
+     * </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.
      * @throws QpidException If the session fails to delete the exchange due to some error.
-     * @see DeleteExchangeOption
+     * @see Option
      */
-    public void deleteExchange(String exchangeName, DeleteExchangeOption... options) throws QpidException;
-    //Todo: Do we need to define more specific exceptions like exchange does not exist?
+    public void exchangeDelete(String exchangeName, Option... options)
+            throws
+            QpidException;
+     //Todo: Do we need to define more specific exceptions like exchange does not exist?
 }