Author: tross
Date: Tue Dec 20 13:33:32 2011
New Revision: 1221254
URL: http://svn.apache.org/viewvc?rev=1221254&view=rev
Log:
QPID-3651 - Improve the Qpid::Messaging::Sender APIs and documentation.
Applied patch from Darryl Pierce.
Modified:
qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/sender.rb
qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/session.rb
qpid/trunk/qpid/cpp/bindings/qpid/ruby/test/test_sender.rb
Modified: qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/sender.rb
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/sender.rb?rev=1221254&r1=1221253&r2=1221254&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/sender.rb (original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/sender.rb Tue Dec 20
13:33:32 2011
@@ -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
Modified: qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/session.rb
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/session.rb?rev=1221254&r1=1221253&r2=1221254&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/session.rb (original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/session.rb Tue Dec 20
13:33:32 2011
@@ -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.
Modified: qpid/trunk/qpid/cpp/bindings/qpid/ruby/test/test_sender.rb
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/ruby/test/test_sender.rb?rev=1221254&r1=1221253&r2=1221254&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/ruby/test/test_sender.rb (original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/ruby/test/test_sender.rb Tue Dec 20
13:33:32 2011
@@ -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
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:commits-subscr...@qpid.apache.org
