Fromating + added release

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

4 files changed, 49 insertions, 74 deletions

diff --git a/java/client/src/main/java/org/apache/qpid/nclient/api/Message.java b/java/client/src/main/java/org/apache/qpid/nclient/api/Message.java
index fd9cead174..f16ab47a22 100644
--- a/java/client/src/main/java/org/apache/qpid/nclient/api/Message.java
+++ b/java/client/src/main/java/org/apache/qpid/nclient/api/Message.java
@@ -75,13 +75,10 @@ public interface Message
      * <p>The message must have been previously acquired either by receiving it in
      * pre-acquire mode or by explicitly acquiring it.
      *
-     * @throws QpidException If the acknowledgement of the message fails due to some error.
+     * @throws QpidException         If the acknowledgement of the message fails due to some error.
      * @throws IllegalStateException If this messages is not acquired.
      */
-    public void acknowledge()
-            throws
-            QpidException,
-            IllegalStateException;
+    public void acknowledge() throws QpidException, IllegalStateException;
 
     /**
      * Acknowledge the receipt of an acquired messages which IDs are within
@@ -91,10 +88,7 @@ public interface Message
      * @throws QpidException         If the acknowledgement of this set of messages fails due to some error.
      * @throws IllegalStateException If some messages are not acquired.
      */
-    public void acknowledge(Message message)
-            throws
-            QpidException,
-            IllegalStateException;
+    public void acknowledge(Message message) throws QpidException, IllegalStateException;
 
     /**
      * Reject a previously acquired message.
@@ -104,10 +98,7 @@ public interface Message
      * @throws QpidException         If this message cannot be rejected dus to some error
      * @throws IllegalStateException If this message is not acquired.
      */
-    public void reject()
-            throws
-            QpidException,
-            IllegalStateException;
+    public void reject() throws QpidException, IllegalStateException;
 
     /**
      * Try to acquire this message hence releasing it form the queue. This means that once acknowledged,
@@ -119,8 +110,13 @@ public interface Message
      * @throws QpidException         If this message cannot be acquired dus to some error
      * @throws IllegalStateException If this message has already been acquired.
      */
-    public boolean acquire()
-            throws
-            QpidException,
-            IllegalStateException;
+    public boolean acquire() throws QpidException, IllegalStateException;
+
+    /**
+     * Give up responsibility for processing this message.
+     *
+     * @throws QpidException          If this message cannot be released dus to some error.
+     * @throws IllegalStateException  If this message has already been acknowledged.
+     */
+    public void release() throws QpidException, IllegalStateException;
 }
diff --git a/java/client/src/main/java/org/apache/qpid/nclient/api/MessageReceiver.java b/java/client/src/main/java/org/apache/qpid/nclient/api/MessageReceiver.java
index 84d38057c3..8019c75fda 100644
--- a/java/client/src/main/java/org/apache/qpid/nclient/api/MessageReceiver.java
+++ b/java/client/src/main/java/org/apache/qpid/nclient/api/MessageReceiver.java
@@ -57,6 +57,8 @@ public interface MessageReceiver extends Resource
 
     /**
      * Stop the delivery of messages to this receiver.
+     * <p>For asynchronous receiver, this operation blocks until the message listener
+     * finishes processing the current message,
      *
      * @throws QpidException         If this receiver fails to be stopped due to some error.
      * @throws IllegalStateException If this receiver is closed or already stopped.
diff --git a/java/client/src/main/java/org/apache/qpid/nclient/api/Resource.java b/java/client/src/main/java/org/apache/qpid/nclient/api/Resource.java
index 47587f1cde..e4970f8694 100644
--- a/java/client/src/main/java/org/apache/qpid/nclient/api/Resource.java
+++ b/java/client/src/main/java/org/apache/qpid/nclient/api/Resource.java
@@ -32,7 +32,10 @@ public interface Resource
 
     /**
      * Close this resource.
-     *
+     * <p> Any blocking receive must return null.
+     * <p> For asynchronous receiver, this operation blocks until the message listener
+     * finishes processing the current message,
+     * 
      * @throws QpidException If the session fails to close this resource due to some error
      */
     public void close() throws
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 8a88079a98..dbe1b68e80 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
@@ -37,9 +37,7 @@ public interface Session
      * @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.
@@ -47,9 +45,7 @@ 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
@@ -58,9 +54,14 @@ 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;
 
     /**
      * Create a message sender for sending messages to queue queueName.
@@ -69,9 +70,7 @@ 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?
 
     /**
@@ -91,9 +90,7 @@ public interface Session
      * @throws QpidException If the session fails to create the receiver due to some error.
      * @see CreateReceiverOption
      */
-    public MessageReceiver createReceiver(String queueName, CreateReceiverOption... options)
-            throws
-            QpidException;
+    public MessageReceiver createReceiver(String queueName, CreateReceiverOption... options) throws QpidException;
     //Todo: Do we need to define more specific exceptions like queue name not valid?
 
     /**
@@ -102,10 +99,7 @@ public interface Session
      * @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.
@@ -113,10 +107,7 @@ 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.
@@ -125,10 +116,7 @@ public interface Session
      * @throws QpidException         If the session fail 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
@@ -147,9 +135,7 @@ public interface Session
      * @throws QpidException If the session fails to declare the queue due to some error.
      * @see DeclareQueueOption
      */
-    public void declareQueue(String queueName, DeclareQueueOption... options)
-            throws
-            QpidException;
+    public void declareQueue(String queueName, DeclareQueueOption... options) throws QpidException;
     //Todo: Do we need to define more specific exceptions like queue name already exist?
 
     /**
@@ -158,12 +144,9 @@ 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 bindQueue(String queueName, String exchangeName, String routingKey) throws QpidException;
     //Todo: Do we need to define more specific exceptions like exchange does not exist?
 
     /**
@@ -174,9 +157,7 @@ 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 unbindQueue(String queueName, String exchangeName, String routingKey) throws QpidException;
     //Todo: Do we need to define more specific exceptions like exchange does not exist?
 
     /**
@@ -184,12 +165,9 @@ 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 purgeQueue(String queueName) throws QpidException;
 
     /**
      * Delet a queue.
@@ -202,9 +180,7 @@ public interface Session
      * @throws QpidException If the session fails to delete the queue due to some error.
      * @see DeleteQueueOption
      */
-    public void deleteQueue(String queueName, DeleteQueueOption options)
-            throws
-            QpidException;
+    public void deleteQueue(String queueName, DeleteQueueOption options) throws QpidException;
 
     /**
      * Declare an exchange.
@@ -218,15 +194,15 @@ public interface Session
      * <li> not passive
      * </ul>
      *
-     * @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.
+     * @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
      */
-    public void declareExchange(String exchangeName, String exchangeClass, String alternateExchange, DeclareExchangeOption... options)
-            throws
-            QpidException;
+    public void declareExchange(String exchangeName, String exchangeClass, String alternateExchange,
+                                DeclareExchangeOption... options) throws QpidException;
     //Todo: Do we need to define more specific exceptions like exchange already exist?
 
     /**
@@ -238,10 +214,8 @@ public interface Session
      * @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 DeleteExchangeOption
      */
-    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 deleteExchange(String exchangeName, DeleteExchangeOption... options) throws QpidException;
+    //Todo: Do we need to define more specific exceptions like exchange does not exist?
 }