You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by tr...@apache.org on 2011/12/20 14:29:04 UTC
svn commit: r1221252 - in /qpid/trunk/qpid/cpp/bindings/qpid/ruby:
lib/qpid/receiver.rb lib/qpid/session.rb test/test_receiver.rb
Author: tross
Date: Tue Dec 20 13:29:04 2011
New Revision: 1221252
URL: http://svn.apache.org/viewvc?rev=1221252&view=rev
Log:
QPID-3655 - Improve the Qpid::Messaging::Receiver APIs and documentation.
Applied patch from Darryl Pierce.
Modified:
qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/receiver.rb
qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/session.rb
qpid/trunk/qpid/cpp/bindings/qpid/ruby/test/test_receiver.rb
Modified: qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/receiver.rb
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/receiver.rb?rev=1221252&r1=1221251&r2=1221252&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/receiver.rb (original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/receiver.rb Tue Dec 20 13:29:04 2011
@@ -25,10 +25,21 @@ module Qpid
module Messaging
- # Receiver defines a type for receiving messages.
+ # Receiver is the entity through which messages are received.
+ #
+ # An instance of Receiver can only be created using an active (not
+ # previously closed) Session.
+ #
+ # ==== Example
+ #
+ # conn = Qpid::Messaging::Connection.new :url => "mybroker:5762"
+ # conn.open
+ # session = conn.create_session
+ # receiver = session.create_receiver "my-sender-queue"
class Receiver
- def initialize(receiver_impl) # :nodoc:
+ def initialize(session, receiver_impl) # :nodoc:
+ @session = session
@receiver_impl = receiver_impl
end
@@ -36,8 +47,30 @@ module Qpid
@receiver_impl
end
- # Retrieves a message from the receiver's local queue, or waits
- # for up to the duration specified for one to become available.
+ # Retrieves a message from the local queue, or waits for up to
+ # the duration specified for one to become available.
+ #
+ # If a block is given, then it will be invaked after the next message
+ # is received or the call times out, passing in the message or nil
+ # respectively.
+ #
+ # ==== Options
+ # * duration - the timeout to wait (def. Duration::FOREVER)
+ #
+ # ==== Examples
+ #
+ # msg = rcvr.get # Uses the default timeout of forever
+ #
+ # msg = rcvr.get Qpid::Messaging::Duration::IMMEDIATE # returns a message or exits immediately
+ #
+ # # passes in a block to handle the received message
+ # rcvr.get Qpid::Messaging::Duration::SECOND do |message|
+ # if message.nil?
+ # puts "No message was received."
+ # else
+ # puts "Received this message: #{message.content}"
+ # end
+ # end
def get(duration = Qpid::Messaging::Duration::FOREVER)
message_impl = @receiver_impl.get duration.duration_impl
create_message_wrapper message_impl unless message_impl.nil?
@@ -45,52 +78,94 @@ module Qpid
# Retrieves a message from the receiver's subscription, or waits
# for up to the duration specified for one to become available.
+ #
+ # If a block is given, then it will be invaked after the next message
+ # is received or the call times out, passing in the message or nil
+ # respectively.
+ #
+ # ==== Options
+ # * duration - the timeout to wait (def. Duration::FOREVER)
+ #
+ # ==== Examples
+ #
+ # msg = rcvr.fetch # Uses the default timeout of forever
+ #
+ # msg = rcvr.fetch Qpid::Messaging::Duration::IMMEDIATE # returns a message or exits immediately
+ #
+ # # passes in a block to handle the received message
+ # rcvr.fetch Qpid::Messaging::Duration::SECOND do |message|
+ # if message.nil?
+ # puts "No message was received."
+ # else
+ # puts "Received this message: #{message.content}"
+ # end
+ # end
def fetch(duration = Qpid::Messaging::Duration::FOREVER)
message_impl = @receiver_impl.fetch duration.duration_impl
create_message_wrapper message_impl unless message_impl.nil?
end
- # Sets the capacity.
+ # Sets the capacity for this +Receiver+.
+ #
+ # ==== Options
+ #
+ # * capacity - the capacity
+ #
+ # ==== Examples
#
- # The capacity for a receiver determines the number of messages that
- # can be held in the receiver before being fetched.
+ # receiver.capacity = 50 # sets the incoming capacity to 50 messages
def capacity=(capacity); @receiver_impl.setCapacity capacity; end
# Returns the capacity.
+ #
+ #
+ # The capacity is the numnber of incoming messages that can be held
+ # locally before being fetched.
+ #
+ # ==== Examples
+ #
+ # puts "The receiver can hold #{rcv.capacity} messages."
def capacity; @receiver_impl.getCapacity; end
- # Returns the number of available messages waiting to be fetched.
+ # Returns the number of slots for receiving messages.
+ #
+ # This differs from +capacity+ in that it is the available slots in
+ # the capacity for holding incoming messages, where available <= capacity.
+ #
+ # ==== Examples
+ #
+ # puts "You can receive #{rcv.available} messages before blocking."
def available; @receiver_impl.getAvailable; end
# Returns the number of messages that have been received and acknowledged
# but whose acknowledgements have not been confirmed by the sender.
def unsettled; @receiver_impl.getUnsettled; end
- # Cancels the reciever.
+ # Closes this +Reciever+.
+ #
+ # This does not affect the +Session+.
def close; @receiver_impl.close; end
# Returns whether the receiver is closed.
+ #
+ # ==== Examples
+ #
+ # recv.close unless recv.closed?
def closed?; @receiver_impl.isClosed; end
- # Returns the name of the receiver
+ # Returns the name of this +Receiver+.
+ #
+ # ==== Examples
+ #
+ # puts "Receiver: #{recv.name}"
def name; @receiver_impl.getName; end
- # Returns the Session for this receiver.
- def session; Qpid::Messaging::Session.new(@receiver_impl.getSession); end
-
- # Returns whether the underlying handle is valid.
- def valid?; @receiver_impl.isValid; end
-
- # Returns whether the underlying handle is null.
- def null?; @receiver_impl.isNull; end
-
- def swap receiver
- @receiver_impl.swap receiver.receiver_impl
- end
+ # Returns the Session for this +Receiver+.
+ def session; @session; end
private
- def create_message_wrapper message_impl
+ def create_message_wrapper message_impl # :nodoc:
Qpid::Messaging::Message.new({}, message_impl)
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=1221252&r1=1221251&r2=1221252&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:29:04 2011
@@ -85,16 +85,17 @@ module Qpid
# Creates a new endpoint for receiving messages.
def create_receiver(address)
- result = nil
+ result = nil
+ receiver_impl = nil
if address.class == Qpid::Messaging::Address
address_impl = address.address_impl
- result = Qpid::Messaging::Receiver.new(@session_impl.createReceiver(address_impl))
+ receiver_impl = @session_impl.createReceiver(address_impl)
else
- result = Qpid::Messaging::Receiver.new(@session_impl.createReceiver(address))
+ receiver_impl = @session_impl.createReceiver(address)
end
- return result
+ Qpid::Messaging::Receiver.new self, receiver_impl
end
# Closes the Session and all associated Senders and Receivers.
@@ -160,7 +161,7 @@ module Qpid
# Fetches the receiver for the next message.
def next_receiver(timeout = Qpid::Messaging::Duration::FOREVER)
receiver_impl = @session_impl.nextReceiver(timeout.duration_impl)
- Qpid::Messaging::Receiver.new receiver_impl
+ Qpid::Messaging::Receiver.new self, receiver_impl
end
# Returns whether there are errors on this session.
Modified: qpid/trunk/qpid/cpp/bindings/qpid/ruby/test/test_receiver.rb
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/ruby/test/test_receiver.rb?rev=1221252&r1=1221251&r2=1221252&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/ruby/test/test_receiver.rb (original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/ruby/test/test_receiver.rb Tue Dec 20 13:29:04 2011
@@ -27,7 +27,8 @@ require 'qpid/receiver'
class TestReceiver < Test::Unit::TestCase
def setup
- @session_impl = flexmock("session")
+ @session = flexmock("session")
+ @session_impl = flexmock("session_impl")
@Message_class = flexmock(Qpid::Messaging::Message)
@Messaging_module = flexmock(Qpid::Messaging)
@@ -37,7 +38,7 @@ class TestReceiver < Test::Unit::TestCas
@receiver_impl = flexmock("receiver")
@other_receiver = flexmock("other_receiver")
@other_receiver_impl = flexmock("other_receiver_impl")
- @receiver = Qpid::Messaging::Receiver.new @receiver_impl
+ @receiver = Qpid::Messaging::Receiver.new @session, @receiver_impl
end
def test_receiver_impl
@@ -192,46 +193,10 @@ class TestReceiver < Test::Unit::TestCas
end
def test_get_session
- @receiver_impl.
- should_receive(:getSession).
- once.
- and_return(@session_impl)
-
result = @receiver.session
assert_not_nil result
- assert_same @session_impl, result.session_impl
- end
-
- def test_is_valid
- @receiver_impl.
- should_receive(:isValid).
- once.
- and_return(false)
-
- assert !@receiver.valid?
- end
-
- def test_is_null
- @receiver_impl.
- should_receive(:isNull).
- once.
- and_return(true)
-
- assert @receiver.null?
- end
-
- def test_swap
- @other_receiver.
- should_receive(:receiver_impl).
- once.
- and_return(@other_receiver_impl)
- @receiver_impl.
- should_receive(:swap).
- once.
- with(@other_receiver_impl)
-
- @receiver.swap @other_receiver
+ assert_same @session, result
end
end
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org