Author: tross
Date: Tue Dec 20 14:20:45 2011
New Revision: 1221269
URL: http://svn.apache.org/viewvc?rev=1221269&view=rev
Log:
QPID-3639 - Refactored the APIs for Qpid::Messaging::Session and modified the
documentation.
Applied patch from Darryl Pierce.
Modified:
qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/connection.rb
qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/session.rb
qpid/trunk/qpid/cpp/bindings/qpid/ruby/test/test_session.rb
Modified: qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/connection.rb
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/connection.rb?rev=1221269&r1=1221268&r2=1221269&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/connection.rb (original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid/connection.rb Tue Dec 20
14:20:45 2011
@@ -113,7 +113,7 @@ module Qpid
else
session = @connection_impl.createSession name
end
- return Session.new(session)
+ return Session.new(self, session)
else
raise RuntimeError.new "No connection available."
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=1221269&r1=1221268&r2=1221269&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
14:20:45 2011
@@ -28,21 +28,35 @@ module Qpid
# A Session represents a distinct conversation between end points.
class Session
- def initialize(session) # :nodoc:
+ def initialize(connection, session) # :nodoc:
+ @connection = connection
@session_impl = session
+ @senders = Hash.new
+ @receivers = Hash.new
end
def session_impl # :nodoc:
@session_impl
end
- # Returns the +Connection+ for the +Session+.
+ # Returns the +Connection+ associated with this session.
def connection
- connection_impl = @session_impl.getConnection
- Qpid::Messaging::Connection.new :impl => connection_impl
+ @connection
end
# Creates a new endpoint for sending messages.
+ #
+ # The +address+ can either be an instance +Address+ or else a
+ # string that describes an address endpoint.
+ #
+ # ==== Arguments
+ #
+ # * +address+ The end point address.
+ #
+ # ==== Examples
+ #
+ # sender = session.create_sender "my-queue;{create:always}"
+ #
def create_sender(address)
_address = address
@@ -50,56 +64,87 @@ module Qpid
_address = address.address_impl
end
- Qpid::Messaging::Sender.new(self, @session_impl.createSender(_address))
- end
-
- # Retrieves the +Sender+ with the specified name.
- def sender(name)
- result = nil
+ sender_impl = @session_impl.createSender(_address)
+ sender_name = sender_impl.getName
- begin
- sender_impl = @session_impl.getSender name
- result = Sender.for_impl sender_impl
- rescue
- # treat any error as a key error
- end
+ @senders[sender_name] = Qpid::Messaging::Sender.new(self, sender_impl)
- raise Qpid::Messaging::KeyError, "No such sender: #{name}" if
result.nil?
- result
+ @senders[sender_name]
end
- # Retrieves the +Receiver+ with the specified name.
- def receiver(name)
- result = nil
-
- begin
- receiver_impl = @session_impl.getReceiver name
- result = Receiver.for_impl receiver_impl
- rescue
- # treat any error as a key error
- end
+ # Retrieves the +Sender+ with the specified name.
+ #
+ # The +Sender+ must have been previously created using
+ # the +create_sender+ method.
+ #
+ # ==== Arguments
+ #
+ # * +name+ The +Sender+ name.
+ #
+ # ==== Examples
+ #
+ # sender = session.sender "my-queue"
+ #
+ def sender(name)
+ raise Qpid::Messaging::KeyError, "No such sender: #{name}" unless
@senders.has_key? name
- raise Qpid::Messaging::KeyError, "No such receiver: #{name}" if
result.nil?
- result
+ @senders[name]
end
# Creates a new endpoint for receiving messages.
+ #
+ # The +address+ can either be an instance +Address+ or else a
+ # string that describes an address endpoint.
+ #
+ # ==== Arguments
+ #
+ # * +address+ The end point address.
+ #
+ # ==== Examples
+ #
+ # receiver = session.create_receiver "my-queue"
+ #
def create_receiver(address)
result = nil
receiver_impl = nil
if address.class == Qpid::Messaging::Address
address_impl = address.address_impl
- receiver_impl = @session_impl.createReceiver(address_impl)
+ receiver_impl = @session_impl.createReceiver address_impl
else
receiver_impl = @session_impl.createReceiver(address)
end
- Qpid::Messaging::Receiver.new self, receiver_impl
+ receiver_name = receiver_impl.getName
+
+ @receivers[receiver_name] = Qpid::Messaging::Receiver.new self,
receiver_impl
+
+ @receivers[receiver_name]
end
- # Closes the Session and all associated Senders and Receivers.
- # All Sessions are closed when the associated Connection is closed.
+ # Retrieves the +Receiver+ with the specified name.
+ #
+ # The +Receiver+ must have been previously created using
+ # the +create_receiver+ method.
+ #
+ # ==== Arguments
+ #
+ # * +name+ The +Receiver+ name.
+ #
+ # ==== Examples
+ #
+ # receiver = session.receiver "my-queue"
+ #
+ def receiver(name)
+ raise Qpid::Messaging::KeyError, "No such receiver: #{name}" unless
@receivers.has_key? name
+
+ @receivers[name]
+ end
+
+ # Closes the +Session+ and all associated +Sender+ and +Receiver+
instances.
+ #
+ # NOTE: All +Session+ instances for a +Connection+ are closed when the
+ # +Connection+ is closed.
def close; @session_impl.close; end
# Commits any pending transactions for a transactional session.
@@ -111,12 +156,20 @@ module Qpid
# Acknowledges one or more outstanding messages that have been received
# on this session.
#
- # If a message is submitted (:message => something_message) then only
- # that message is acknowledged. Otherwise all messsages are acknowledged.
+ # ==== Arguments
+ #
+ # * :message - if specified, then only the +Message+ specified is
acknowledged
+ # * :sync - if true then the call will block until processed by the
server (def. false)
+ #
+ # ==== Examples
+ #
+ # session.acknowledge # acknowledges all received
messages
+ # session.acknowledge :message => message # acknowledge one message
+ # session.acknowledge :sync => true # blocks until the call
completes
#
- # If :sync => true then the call will block until the server completes
- # processing the acknowledgements.
- # If :sync => true then the call will block until processed by the
server (def. false)
+ #--
+ # TODO: Add an optional block to be used for blocking calls.
+ #++
def acknowledge(args = {})
sync = args[:sync] || false
message = args[:message] if args[:message]
@@ -128,7 +181,8 @@ module Qpid
end
end
- # Rejects the specified message. A rejected message will not be
redelivered.
+ # Rejects the specified message. A rejected message will not be
+ # redelivered.
#
# NOTE: A message cannot be rejected once it has been acknowledged.
def reject(message); @session_impl.reject message.message_impl; end
@@ -141,43 +195,73 @@ module Qpid
# Requests synchronization with the server.
#
- # If :block => true then the call will block until the server
acknowledges.
+ # ==== Arguments
#
- # If :block => false (default) then the call will complete and the server
- # will send notification on completion.
+ # * :block - if true then the call blocks until the server acknowledges
it (def. false)
+ #
+ #--
+ # TODO: Add an optional block to be used for blocking calls.
+ #++
def sync(args = {})
block = args[:block] || false
@session_impl.sync block
end
- # Returns the total number of receivable messages, and messages already
received,
- # by Receivers associated with this session.
+ # Returns the total number of receivable messages, and messages already
+ # received, by +Receiver+ instances associated with this +Session+.
def receivable; @session_impl.getReceivable; end
# Returns the number of messages that have been acknowledged by this
session
# whose acknowledgements have not been confirmed as processed by the
server.
def unsettled_acks; @session_impl.getUnsettledAcks; end
- # Fetches the receiver for the next message.
- def next_receiver(timeout = Qpid::Messaging::Duration::FOREVER)
+ # Fetches the +Receiver+ for the next message.
+ #
+ # ==== Arguments
+ #
+ # * timeout - time to wait for a +Receiver+ before timing out
+ #
+ # ==== Examples
+ #
+ # recv = session.next_receiver # wait forever for the next +Receiver+
+ # # execute a block on the next receiver
+ # session.next_receiver do |recv|
+ # msg = recv.get
+ # puts "Received message: #{msg.content}"
+ # end
+ def next_receiver(timeout = Qpid::Messaging::Duration::FOREVER, &block)
receiver_impl = @session_impl.nextReceiver(timeout.duration_impl)
- Qpid::Messaging::Receiver.new self, receiver_impl
- end
- # Returns whether there are errors on this session.
- def error?; @session_impl.hasError; end
-
- def check_error; @session_impl.checkError; end
+ unless receiver_impl.nil?
+ recv = Qpid::Messaging::Receiver.new self, receiver_impl
+ block.call recv unless block.nil?
+ end
- # Returns if the underlying session is valid.
- def valid?; @session_impl.isValid; end
+ return recv
+ end
- # Returns if the underlying session is null.
- def null?; @session_impl.isNull; end
+ # Returns true if there were exceptions on this session.
+ #
+ # ==== Examples
+ #
+ # puts "There were session errors." if @session.errors?
+ def errors?; @session_impl.hasError; end
- def swap session
- @session_impl.swap session.session_impl
- end
+ # If the +Session+ has been rendered invalid due to some exception,
+ # this method will result in that exception being raised.
+ #
+ # If none have occurred, then no exceptions are raised.
+ #
+ # ==== Examples
+ #
+ # if @session.errors?
+ # begin
+ # @session.errors
+ # rescue Exception => error
+ # puts "An error occurred: #{error}"
+ # end
+ # end
+ def errors; @session_impl.checkError; end
end
Modified: qpid/trunk/qpid/cpp/bindings/qpid/ruby/test/test_session.rb
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/ruby/test/test_session.rb?rev=1221269&r1=1221268&r2=1221269&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/ruby/test/test_session.rb (original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/ruby/test/test_session.rb Tue Dec 20
14:20:45 2011
@@ -55,7 +55,7 @@ class TestSession < Test::Unit::TestCase
@duration = flexmock("duration")
@duration_impl = flexmock("duration_impl")
- @session = Qpid::Messaging::Session.new(@session_impl)
+ @session = Qpid::Messaging::Session.new(@connection, @session_impl)
end
def test_create_sender_with_Address
@@ -71,6 +71,10 @@ class TestSession < Test::Unit::TestCase
once.
with(@address_impl).
and_return(@sender_impl)
+ @sender_impl.
+ should_receive(:getName).
+ once.
+ and_return("foo")
result = @session.create_sender @address
@@ -83,10 +87,15 @@ class TestSession < Test::Unit::TestCase
once.
with_any_args.
and_return(@sender_impl)
+ @sender_impl.
+ should_receive(:getName).
+ once.
+ and_return("my-queue")
result = @session.create_sender("my-queue")
assert_not_nil result
+ assert_same result.sender_impl, @sender_impl
end
def test_create_sender_with_address_string
@@ -95,6 +104,10 @@ class TestSession < Test::Unit::TestCase
once.
with("my-queue;{create:always}").
and_return(@sender_impl)
+ @sender_impl.
+ should_receive(:getName).
+ once.
+ and_return("foo")
result = @session.create_sender "my-queue;{create:always}"
@@ -114,6 +127,10 @@ class TestSession < Test::Unit::TestCase
once.
with(@address_impl).
and_return(@receiver_impl)
+ @receiver_impl.
+ should_receive(:getName).
+ once.
+ and_return("my-queue")
result = @session.create_receiver(@address)
@@ -126,6 +143,10 @@ class TestSession < Test::Unit::TestCase
once.
with("my-queue").
and_return(@receiver_impl)
+ @receiver_impl.
+ should_receive(:getName).
+ once.
+ and_return("my-queue")
result = @session.create_receiver("my-queue")
@@ -320,63 +341,53 @@ class TestSession < Test::Unit::TestCase
assert_same @receiver_impl, result.receiver_impl
end
- def test_sender
+ def test_sender_with_invalid_name
+ assert_raises(Qpid::Messaging::KeyError) { @session.sender "farkle" }
+ end
+
+ def test_get_sender
@session_impl.
- should_receive(:getSender).
+ should_receive(:createSender).
once.
- with("farkle").
+ with("my-queue").
and_return(@sender_impl)
- @Sender_class.
- should_receive(:for_impl).
+ @sender_impl.
+ should_receive(:getName).
once.
- with(@sender_impl).
- and_return(@sender)
+ and_return("my-queue")
- result = @session.sender "farkle"
+ sender = @session.create_sender "my-queue"
+ result = @session.sender "my-queue"
- assert_same @sender, result
+ assert_not_nil sender
+ assert_same sender, result
end
- def test_sender_with_invalid_name
+ def test_get_receiver
@session_impl.
- should_receive(:getSender).
- once.
- with("farkle").
- and_throw(RuntimeError)
-
- assert_raise(Qpid::Messaging::KeyError) {@session.sender "farkle"}
- end
-
- def test_receiver
- @session_impl.
- should_receive(:getReceiver).
+ should_receive(:createReceiver).
once.
- with("farkle").
+ with("my-queue").
and_return(@receiver_impl)
- @Receiver_class.
- should_receive(:for_impl).
+ @receiver_impl.
+ should_receive(:getName).
once.
- with(@receiver_impl).
- and_return(@receiver)
+ and_return("my-queue")
- result = @session.receiver "farkle"
+ receiver = @session.create_receiver "my-queue"
+ result = @session.receiver "my-queue"
- assert_same @receiver, result
+ assert_not_nil receiver
+ assert_same receiver, result
end
- def test_receiver_with_invalid_name
- @session_impl.
- should_receive(:getReceiver).
- once.
- with("farkle").
- and_throw(RuntimeError)
-
- assert_raise(Qpid::Messaging::KeyError) {@session.receiver "farkle"}
+ def test_get_receiver_with_invalid_name
+ assert_raise(Qpid::Messaging::KeyError) { @session.receiver "farkle" }
end
def test_connection
- @session_impl.
- should_receive(:getConnection).
+ @connection.
+ should_receive(:connection_impl).
once.
and_return(@connection_impl)
@@ -391,7 +402,7 @@ class TestSession < Test::Unit::TestCase
once.
and_return(false)
- assert !@session.error?
+ assert !@session.errors?
end
def test_error
@@ -400,46 +411,24 @@ class TestSession < Test::Unit::TestCase
once.
and_return(true)
- assert @session.error?
+ assert @session.errors?
end
- def test_check_error
+ def test_errors
@session_impl.
should_receive(:checkError).
- once
-
- @session.check_error
- end
-
- def test_is_valid
- @session_impl.
- should_receive(:isValid).
once.
- and_return(false)
+ and_raise(Exception, "Expected")
- assert !@session.valid?
+ assert_raises(Exception) { @session.errors }
end
- def test_is_null
+ def test_errors_without_exceptions
@session_impl.
- should_receive(:isNull).
- once.
- and_return(false)
-
- assert !@session.null?
- end
-
- def test_swap
- @other_session.
- should_receive(:session_impl).
- once.
- and_return(@other_session_impl)
- @session_impl.
- should_receive(:swap).
- once.
- with(@other_session_impl)
+ should_receive(:checkError).
+ once
- @session.swap @other_session
+ assert_nothing_raised { @session.errors }
end
end
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:commits-subscr...@qpid.apache.org
