QPID-3651 - Improve the Qpid::Messaging::Sender APIs and documentation.

Applied patch from Darryl Pierce.


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

3 files changed, 85 insertions, 60 deletions

diff --git a/cpp/bindings/qpid/ruby/lib/qpid/sender.rb b/cpp/bindings/qpid/ruby/lib/qpid/sender.rb
index b8627401f8..345702a565 100644
--- a/cpp/bindings/qpid/ruby/lib/qpid/sender.rb
+++ b/cpp/bindings/qpid/ruby/lib/qpid/sender.rb
@@ -21,10 +21,21 @@ module Qpid
 
   module Messaging
 
-    # Sender defines a type for sending messages.
+    # Sender is the entity through which messages sent.
+    #
+    # An instance of Sender can only be created using an active (not previously
+    # closed) Session.
+    #
+    # ==== Examples
+    #
+    #   conn    = Qpid::Messaging::Connection.new :url => "mybroker:5762"
+    #   conn.open
+    #   session = conn.create_session
+    #   sender  = session.create_session "my-sender-queue;{create:always}"
     class Sender
 
-      def initialize(sender_impl) # :nodoc:
+      def initialize(session, sender_impl) # :nodoc:
+        @session     = session
         @sender_impl = sender_impl
       end
 
@@ -33,46 +44,95 @@ module Qpid
       end
 
       # Sends a message.
-      def send(message, args = {})
+      #
+      # If a block is given, then it will be invoked after the message
+      # is sent.
+      #
+      # ==== Options
+      #
+      # * message - The message to send.
+      # * :sync - See note below on synching.
+      #
+      # ==== Synching
+      #
+      # If :sync => true, then the call will block until the broker confirms
+      # receipt of the message. Otherwise it will only block for available
+      # capacity; i.e., until pending is equal to capacity.
+      #
+      # ==== Examples
+      #
+      #   sender.send message do |message|
+      #     puts "Message sent: #{message.content}"
+      #   end
+      #
+      def send(message, args = {}, &block)
         sync = args[:sync] || false
         @sender_impl.send message.message_impl, sync
+        block.call message unless block.nil?
       end
 
-      # Closes the sender.
+      # Closes this +Sender+.
+      #
+      # This does not affect the +Session+.
       def close; @sender_impl.close; end
 
-      # Returns the name for the sender.
+      # Returns the human-readable name for this +Sender+.
+      #
+      # ==== Examples
+      #
+      # puts "Sender: #{sender.name}"
       def name; @sender_impl.getName; end
 
-      # Sets the capacity for the sender, which is the number of outgoing
-      # messages that can be held pending confirmation or receipt by
-      # the broker.
+      # Sets the capacity for this +Sender+.
+      #
+      # The capacity is the number of outgoing messages that can be held
+      # pending confirmation or receipt by the broker.
+      #
+      # ==== Options
+      #
+      # * capacity - the capacity
+      #
+      # ==== Examples
+      #
+      #   sender.capacity = 50 # sets the outgoing capacity to 50 messages
       def capacity=(capacity); @sender_impl.setCapacity capacity; end
 
       # Returns the capacity.
+      #
+      # The capacity is the total number of outgoing messages that can be
+      # sent before a called to +send+ begins to block by default.
+      #
+      # ==== Examples
+      #
+      #   puts "You can send a maximum of #{sender.capacity} messages."
       def capacity; @sender_impl.getCapacity; end
 
       # Returns the number of messages sent that are pending receipt
       # confirmation by the broker.
+      #
+      # ==== Examples
+      #
+      #   if sender.unsettled > 0
+      #     puts "There are #{sender.unsettled} messages pending."
+      #   end
       def unsettled; @sender_impl.getUnsettled; end
 
-      # Returns the available capacity for sending messages.
+      # Returns the available slots for sending messages.
+      #
+      # This differs from +capacity+ in that it is the available slots in
+      # the senders capacity for holding outgoing messages. The difference
+      # between capacity and available is the number of messages that
+      # have not been delivered yet.
+      #
+      # ==== Examples
+      #
+      #   puts "You can send #{sender.available} messages before blocking."
       def available
         @sender_impl.getAvailable
       end
 
-      # Returns the Session for this sender.
-      def session; Qpid::Messaging::Session.new @sender_impl.getSession; end
-
-      # Returns if the underlying sender is valid.
-      def valid?; @sender_impl.isValid; end
-
-      # Returns if the underlying sender is null.
-      def null?; @sender_impl.isNull; end
-
-      def swap sender
-        @sender_impl.swap sender.sender_impl
-      end
+      # Returns the +Session+ for this sender.
+      def session; @session; end
 
     end
 
diff --git a/cpp/bindings/qpid/ruby/lib/qpid/session.rb b/cpp/bindings/qpid/ruby/lib/qpid/session.rb
index 3716231035..507f27a1bd 100644
--- a/cpp/bindings/qpid/ruby/lib/qpid/session.rb
+++ b/cpp/bindings/qpid/ruby/lib/qpid/session.rb
@@ -50,7 +50,7 @@ module Qpid
           _address = address.address_impl
         end
 
-        Qpid::Messaging::Sender.new(@session_impl.createSender(_address))
+        Qpid::Messaging::Sender.new(self, @session_impl.createSender(_address))
       end
 
       # Retrieves the +Sender+ with the specified name.
diff --git a/cpp/bindings/qpid/ruby/test/test_sender.rb b/cpp/bindings/qpid/ruby/test/test_sender.rb
index 4388648388..61da9e5771 100644
--- a/cpp/bindings/qpid/ruby/test/test_sender.rb
+++ b/cpp/bindings/qpid/ruby/test/test_sender.rb
@@ -30,11 +30,12 @@ class TestSender < Test::Unit::TestCase
     @messaging = flexmock(Qpid::Messaging)
     @message = flexmock("message")
 
+    @session      = flexmock("session")
     @session_impl = flexmock("session_impl")
 
     @sender_impl = flexmock("sender_impl")
     @other_sender_impl = flexmock("other_sender_impl")
-    @sender = Qpid::Messaging::Sender.new @sender_impl
+    @sender = Qpid::Messaging::Sender.new @session, @sender_impl
     @other_sender = flexmock("other_sender")
   end
 
@@ -137,46 +138,10 @@ class TestSender < Test::Unit::TestCase
   end
 
   def test_session
-    @sender_impl.
-      should_receive(:getSession).
-      once.
-      and_return(@session_impl)
-
     result = @sender.session
 
     assert_not_nil result
-    assert_same @session_impl, result.session_impl
-  end
-
-  def test_is_valid
-    @sender_impl.
-      should_receive(:isValid).
-      once.
-      and_return(true)
-
-    assert @sender.valid?
-  end
-
-  def test_is_null
-    @sender_impl.
-      should_receive(:isNull).
-      once.
-      and_return(false)
-
-    assert !@sender.null?
-  end
-
-  def test_swap
-    @other_sender.
-      should_receive(:sender_impl).
-      once.
-      and_return(@other_sender_impl)
-    @sender_impl.
-      should_receive(:swap).
-      once.
-      with(@other_sender_impl)
-
-    @sender.swap @other_sender
+    assert_same @session, result
   end
 
 end