Qpid-730. Removed durable and subscription name from consumer builder, as they are not to do with consume but queue declaration. Durable subscribers must provide their own fixed queue names.

git-svn-id: https://svn.apache.org/repos/asf/incubator/qpid/branches/M2.1@614184 13f79535-47bb-0310-9956-ffa450edef68

4 files changed, 94 insertions, 44 deletions

diff --git a/dotnet/Qpid.Messaging/IChannel.cs b/dotnet/Qpid.Messaging/IChannel.cs
index 10225d156b..461867b34a 100644
--- a/dotnet/Qpid.Messaging/IChannel.cs
+++ b/dotnet/Qpid.Messaging/IChannel.cs
@@ -25,20 +25,35 @@ namespace Apache.Qpid.Messaging
     public delegate void MessageReceivedDelegate(IMessage msg);
     
     /// <summary>
-    /// Interface used to manipulate an AMQP channel. 
-    /// </summary>
-    /// <remarks>
-    /// You can create a channel by using the CreateChannel() method
+    /// IChannel provides methods to access the commands in AMQP that operate at the channel level. This can be summarized as
+    /// the ability to declare queues and exchanges, bind queues to exchanges, create messages of various types, declare transaction
+    /// boundaries (commit and rollback), and to set up producers and consumers on the channel.
+    ///
+    /// <p/>You can create a channel by using the CreateChannel() method
     /// of the connection object.
-    /// </remarks>
+    ///
+    /// <p/><table id="crc"><caption>CRC Card</caption>
+    /// <tr><th> Responsibilities
+    /// <tr><td> Declare queues.
+    /// <tr><td> Declare exchanges.
+    /// <tr><td> Bind queues to exchanges.
+    /// <tr><td> Create messages.
+    /// <tr><td> Set up message consumers on the channel.
+    /// <tr><td> Set up message producers on the channel.
+    /// <tr><td> Commit the current transaction.
+    /// <tr><td> Roll-back the current transaction.
+    /// <tr><td> Close the channel.
+    /// </table>
+    /// </summary>
     public interface IChannel : IDisposable, ICloseable
     {
         /// <summary>
-        /// Acknowledge mode for messages received
+        /// Acknowledge mode for messages received.
         /// </summary>
         AcknowledgeMode AcknowledgeMode { get; }
+
         /// <summary>
-        /// True if the channel should use transactions
+        /// True if the channel should use transactions.
         /// </summary>
         bool Transacted { get; }
 
@@ -61,55 +76,59 @@ namespace Apache.Qpid.Messaging
         int DefaultPrefetchHigh { get; }
 
         /// <summary>
-        /// Declare a new exchange
+        /// Declare a new exchange.
         /// </summary>
         /// <param name="exchangeName">Name of the exchange</param>
         /// <param name="exchangeClass">Class of the exchange, from <see cref="ExchangeClassConstants"/></param>
         void DeclareExchange(string exchangeName, string exchangeClass);
+
         /// <summary>
-        /// Declare a new exchange using the default exchange class
+        /// Declare a new exchange using the default exchange class.
         /// </summary>
         /// <param name="exchangeName">Name of the exchange</param>
         void DeleteExchange(string exchangeName);
 
         /// <summary>
-        /// Declare a new queue with the specified set of arguments
+        /// Declare a new queue with the specified set of arguments.
         /// </summary>
         /// <param name="queueName">Name of the queue</param>
         /// <param name="isDurable">True if the queue should be durable</param>
         /// <param name="isExclusive">True if the queue should be exclusive to this channel</param>
         /// <param name="isAutoDelete">True if the queue should be deleted when the channel closes</param>
         void DeclareQueue(string queueName, bool isDurable, bool isExclusive, bool isAutoDelete);
+
         /// <summary>
-        /// Delete a queue with the specifies arguments
+        /// Delete a queue with the specifies arguments.
         /// </summary>
         /// <param name="queueName">Name of the queue to delete</param>
         /// <param name="ifUnused">If true, the queue will not deleted if it has no consumers</param>
         /// <param name="ifEmpty">If true, the queue will not deleted if it has no messages</param>
         /// <param name="noWait">If true, the server will not respond to the method</param>
         void DeleteQueue(string queueName, bool ifUnused, bool ifEmpty, bool noWait);
+
         /// <summary>
-        /// Generate a new Unique name to use for a queue
+        /// Generate a new Unique name to use for a queue.
         /// </summary>
         /// <returns>A unique name to this channel</returns>
         string GenerateUniqueName();
 
         /// <summary>
-        /// Removes all messages from a queue
+        /// Removes all messages from a queue.
         /// </summary>
         /// <param name="queueName">Name of the queue to delete</param>
         /// <param name="noWait">If true, the server will not respond to the method</param>
         void PurgeQueue(string queueName, bool noWait);
         
         /// <summary>
-        /// Bind a queue to the specified exchange
+        /// Bind a queue to the specified exchange.
         /// </summary>
         /// <param name="queueName">Name of queue to bind</param>
         /// <param name="exchangeName">Name of exchange to bind to</param>
         /// <param name="routingKey">Routing key</param>
         void Bind(string queueName, string exchangeName, string routingKey);
+
         /// <summary>
-        /// Bind a queue to the specified exchange
+        /// Bind a queue to the specified exchange.
         /// </summary>
         /// <param name="queueName">Name of queue to bind</param>
         /// <param name="exchangeName">Name of exchange to bind to</param>
@@ -118,28 +137,32 @@ namespace Apache.Qpid.Messaging
         void Bind(string queueName, string exchangeName, string routingKey, IFieldTable args);
 
         /// <summary>
-        /// Create a new empty message with no body
+        /// Create a new empty message with no body.
         /// </summary>
         /// <returns>The new message</returns>
         IMessage CreateMessage();
+
         /// <summary>
-        /// Create a new message of the specified MIME type
+        /// Create a new message of the specified MIME type.
         /// </summary>
         /// <param name="mimeType">The mime type to create</param>
         /// <returns>The new message</returns>
         IMessage CreateMessage(string mimeType);
+
         /// <summary>
-        /// Creates a new message for bytes (application/octet-stream)
+        /// Creates a new message for bytes (application/octet-stream).
         /// </summary>
         /// <returns>The new message</returns>
         IBytesMessage CreateBytesMessage();
+
         /// <summary>
-        /// Creates a new text message (text/plain) with empty content
+        /// Creates a new text message (text/plain) with empty content.
         /// </summary>
         /// <returns>The new message</returns>
         ITextMessage CreateTextMessage();
+
         /// <summary>
-        /// Creates a new text message (text/plain) with a body
+        /// Creates a new text message (text/plain) with a body.
         /// </summary>
         /// <param name="initialValue">Initial body of the message</param>
         /// <returns>The new message</returns>
@@ -148,33 +171,29 @@ namespace Apache.Qpid.Messaging
         #region Consuming
         
         /// <summary>
-        /// Creates a new Consumer using the builder pattern
+        /// Creates a new Consumer using the builder pattern.
         /// </summary>
         /// <param name="queueName">Name of queue to receive messages from</param>
         /// <returns>The builder object</returns>
         MessageConsumerBuilder CreateConsumerBuilder(string queueName);
 
         /// <summary>
-        /// Creates a new consumer
+        /// Creates a new consumer.
         /// </summary>
         /// <param name="queueName">Name of queue to receive messages from</param>
         /// <param name="prefetchLow">Low prefetch value</param>
         /// <param name="prefetchHigh">High prefetch value</param>
         /// <param name="noLocal">If true, messages sent on this channel will not be received by this consumer</param>
         /// <param name="exclusive">If true, the consumer opens the queue in exclusive mode</param>
-        /// <param name="durable">If true, create a durable subscription</param>
-        /// <param name="subscriptionName">Subscription name</param>
         /// <returns>The new consumer</returns>
         IMessageConsumer CreateConsumer(string queueName,
                                         int prefetchLow, 
                                         int prefetchHigh,
                                         bool noLocal,
-                                        bool exclusive,
-                                        bool durable,
-                                        string subscriptionName);
+                                        bool exclusive);
         
         /// <summary>
-        /// Unsubscribe from a queue
+        /// Unsubscribe from a queue.
         /// </summary>
         /// <param name="subscriptionName">Subscription name</param>
         void Unsubscribe(string subscriptionName);
@@ -184,13 +203,13 @@ namespace Apache.Qpid.Messaging
         #region Publishing
 
         /// <summary>
-        /// Create a new message publisher using the builder pattern
+        /// Create a new message publisher using the builder pattern.
         /// </summary>
         /// <returns>The builder object</returns>
         MessagePublisherBuilder CreatePublisherBuilder();
         
         /// <summary>
-        /// Create a new message publisher
+        /// Create a new message publisher.
         /// </summary>
         /// <param name="exchangeName">Name of exchange to publish to</param>
         /// <param name="routingKey">Routing key</param>
@@ -214,15 +233,17 @@ namespace Apache.Qpid.Messaging
         #region Transactions
         
         /// <summary>
-        /// Recover after transaction failure
+        /// Recover after transaction failure.
         /// </summary>
         void Recover();
+
         /// <summary>
-        /// Commit the transaction
+        /// Commit the transaction.
         /// </summary>
         void Commit();
+
         /// <summary>
-        /// Rollback the transaction
+        /// Rollback the transaction.
         /// </summary>
         void Rollback();
 
diff --git a/dotnet/Qpid.Messaging/ICloseable.cs b/dotnet/Qpid.Messaging/ICloseable.cs
index 139dc8bf45..3c9d66047d 100644
--- a/dotnet/Qpid.Messaging/ICloseable.cs
+++ b/dotnet/Qpid.Messaging/ICloseable.cs
@@ -24,6 +24,11 @@ namespace Apache.Qpid.Messaging
 {

     /// <summary>An ICloseable is a resource that can be explicitly closed. Generally speaking a closed resource can no longer be used, and the

     /// act of closing a resource is usually interpreted as a signal that the closed item can have its resource cleaned up and de-allocated.

+    ///

+    /// <p/><table id="crc"><caption>CRC Card</caption>

+    /// <tr><th> Responsibilities <th> Collaborations

+    /// <tr><td> Close (and clean-up) a resource.

+    /// </table>

     /// </summary>

     public interface ICloseable

     {

diff --git a/dotnet/Qpid.Messaging/IMessageConsumer.cs b/dotnet/Qpid.Messaging/IMessageConsumer.cs
index 46cc681d92..86b5405707 100644
--- a/dotnet/Qpid.Messaging/IMessageConsumer.cs
+++ b/dotnet/Qpid.Messaging/IMessageConsumer.cs
@@ -61,12 +61,14 @@ namespace Apache.Qpid.Messaging
       /// </summary>
       /// <returns>The message received</returns>
       IMessage Receive();
+
       /// <summary>
       /// Wait the specified time until a message is receive from the broker
       /// </summary>
       /// <param name="delay">Maximum number of milliseconds to wait for a message</param>
       /// <returns>The message received, or null if the timeout expires</returns>
       IMessage Receive(long delay);
+
       /// <summary>
       /// Return a message if one is already available in the channel. 
       /// Does not wait for one to be received from the broker.
diff --git a/dotnet/Qpid.Messaging/MessageConsumerBuilder.cs b/dotnet/Qpid.Messaging/MessageConsumerBuilder.cs
index 2d6f76d639..fbf94d7c27 100644
--- a/dotnet/Qpid.Messaging/MessageConsumerBuilder.cs
+++ b/dotnet/Qpid.Messaging/MessageConsumerBuilder.cs
@@ -20,17 +20,35 @@
  */
 namespace Apache.Qpid.Messaging
 {
+    /// <summary>
+    /// MessageConsumerBuilder provides a builder with a fluent interface to assist with creating message consumers on a channel.
+    ///
+    /// <p/><table id="crc"><caption>CRC Card</caption>
+    /// <tr><th> Responsibilities <th> Collaborations
+    /// <tr><td> Create message consumers from consume parameters. <td> <see cref="IChannel">
+    /// </table>
+    /// </summary>
+    ///
+    /// <remarks>It may be better to replace the Create method with a DeclareBindAndCreate method, that declares and binds the consumers queue,
+    /// as well as creating the consumer. This is a common use case, so the method will generally be usefull. Need to consider situations where
+    /// the declare and bind is not to be done, for example when resubscribing to a durable subscription. There may be others too.</remarks>
     public class MessageConsumerBuilder
     {
         private bool _noLocal = false;
+
         private bool _exclusive = false;
-        private bool _durable = false;
-        private string _subscriptionName = null;
+
+        //private bool _durable = false;
+        //private string _subscriptionName = null;
+
         private IChannel _channel;
+
         private readonly string _queueName;
+
         private int _prefetchLow;
-        private int _prefetchHigh;
 
+        private int _prefetchHigh;
+        
         public MessageConsumerBuilder(IChannel channel, string queueName)
         {
             _channel = channel;
@@ -38,46 +56,50 @@ namespace Apache.Qpid.Messaging
             _prefetchHigh = _channel.DefaultPrefetchHigh;
             _prefetchLow = _channel.DefaultPrefetchLow;
         }
-
+        
         public MessageConsumerBuilder WithPrefetchLow(int prefetchLow)
         {
             _prefetchLow = prefetchLow;
             return this;
         }
-
+        
         public MessageConsumerBuilder WithPrefetchHigh(int prefetchHigh)
         {
             _prefetchHigh = prefetchHigh;
             return this;
         }
-
+        
         public MessageConsumerBuilder WithNoLocal(bool noLocal)
         {
             _noLocal = noLocal;
             return this;
         }
-
+        
         public MessageConsumerBuilder WithExclusive(bool exclusive)
         {
             _exclusive = exclusive;
             return this;
         }
-
+        
+        /*
         public MessageConsumerBuilder WithDurable(bool durable)
         {
             _durable = durable;
             return this;
         }
-
+        */
+        
+        /*
         public MessageConsumerBuilder WithSubscriptionName(string subscriptionName)
         {
             _subscriptionName = subscriptionName;
             return this;
         }
-
+        */
+        
         public IMessageConsumer Create()
         {
-            return _channel.CreateConsumer(_queueName, _prefetchLow, _prefetchHigh, _noLocal, _exclusive, _durable, _subscriptionName);
+            return _channel.CreateConsumer(_queueName, _prefetchLow, _prefetchHigh, _noLocal, _exclusive);
         }
     }
 }