QPID-3551 - Refactors the Qpid::Messaging::Connection APIs.

Applied patch from Darryl Pierce.


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

11 files changed, 121 insertions, 70 deletions

diff --git a/qpid/cpp/bindings/qpid/ruby/examples/client.rb b/qpid/cpp/bindings/qpid/ruby/examples/client.rb
index f42f25cfc9..86ec1b7254 100644
--- a/qpid/cpp/bindings/qpid/ruby/examples/client.rb
+++ b/qpid/cpp/bindings/qpid/ruby/examples/client.rb
@@ -25,7 +25,7 @@ if __FILE__ == $0
   broker  = ARGV[1] || "amqp:tcp:localhost:5672"
   options = ARGV[2] || ""
 
-  connection = Qpid::Messaging::Connection.new broker, options
+  connection = Qpid::Messaging::Connection.new :url => broker, :options => options
   connection.open
   session = connection.create_session
   sender = session.create_sender "service_queue"
diff --git a/qpid/cpp/bindings/qpid/ruby/examples/drain.rb b/qpid/cpp/bindings/qpid/ruby/examples/drain.rb
index a6cf35e189..9e8f699e8b 100644
--- a/qpid/cpp/bindings/qpid/ruby/examples/drain.rb
+++ b/qpid/cpp/bindings/qpid/ruby/examples/drain.rb
@@ -73,7 +73,7 @@ opts.parse!(ARGV)
 
 options[:address] = ARGV[0] || ""
 
-connection = Qpid::Messaging::Connection.new options[:broker], options[:connection_options]
+connection = Qpid::Messaging::Connection.new :url => options[:broker], :options => options[:connection_options]
 connection.open
 
 def render_map map
diff --git a/qpid/cpp/bindings/qpid/ruby/examples/hello_world.rb b/qpid/cpp/bindings/qpid/ruby/examples/hello_world.rb
index 703febeba1..c014fb8bd5 100644
--- a/qpid/cpp/bindings/qpid/ruby/examples/hello_world.rb
+++ b/qpid/cpp/bindings/qpid/ruby/examples/hello_world.rb
@@ -30,7 +30,7 @@ if __FILE__ == $0
   address = ARGV[1] || "amq.topic"
   options = ARGV[2] || ""
 
-  connection = Qpid::Messaging::Connection.new broker
+  connection = Qpid::Messaging::Connection.new :url => broker, :options => options
   connection.open
   session    = connection.create_session
   receiver   = session.create_receiver address
diff --git a/qpid/cpp/bindings/qpid/ruby/examples/map_receiver.rb b/qpid/cpp/bindings/qpid/ruby/examples/map_receiver.rb
index 805943a0a4..e08bd295ba 100644
--- a/qpid/cpp/bindings/qpid/ruby/examples/map_receiver.rb
+++ b/qpid/cpp/bindings/qpid/ruby/examples/map_receiver.rb
@@ -25,7 +25,7 @@ broker  = ARGV[0] || "amqp:tcp:127.0.0.1:5672"
 address = ARGV[1] || "message_queue; {create: always}"
 options = ARGV[2] || ""
 
-connection = Qpid::Messaging::Connection.new broker, options
+connection = Qpid::Messaging::Connection.new :url => broker, :options => options
 connection.open
 
 def display_value value
diff --git a/qpid/cpp/bindings/qpid/ruby/examples/map_sender.rb b/qpid/cpp/bindings/qpid/ruby/examples/map_sender.rb
index fa0c6e4562..3fb7ca58e3 100644
--- a/qpid/cpp/bindings/qpid/ruby/examples/map_sender.rb
+++ b/qpid/cpp/bindings/qpid/ruby/examples/map_sender.rb
@@ -25,7 +25,7 @@ broker  = ARGV[0] || "amqp:tcp:127.0.0.1:5672"
 address = ARGV[1] || "message_queue; {create: always}"
 options = ARGV[2] || []
 
-connection = Qpid::Messaging::Connection.new broker, options
+connection = Qpid::Messaging::Connection.new :url => broker, :options => options
 connection.open
 
 begin
diff --git a/qpid/cpp/bindings/qpid/ruby/examples/server.rb b/qpid/cpp/bindings/qpid/ruby/examples/server.rb
index ead9d58472..0cc0e30216 100644
--- a/qpid/cpp/bindings/qpid/ruby/examples/server.rb
+++ b/qpid/cpp/bindings/qpid/ruby/examples/server.rb
@@ -25,7 +25,7 @@ if __FILE__ == $0
   broker  = ARGV[0] || "amqp:tcp:localhost:5672"
   options = ARGV[1] || ""
 
-  connection = Qpid::Messaging::Connection.new broker, options
+  connection = Qpid::Messaging::Connection.new :url => broker, :options =>options
   connection.open
   session = connection.create_session
   receiver = session.create_receiver "service_queue; {create:always}"
diff --git a/qpid/cpp/bindings/qpid/ruby/examples/spout.rb b/qpid/cpp/bindings/qpid/ruby/examples/spout.rb
index c012e31f9d..ecc47fb15a 100644
--- a/qpid/cpp/bindings/qpid/ruby/examples/spout.rb
+++ b/qpid/cpp/bindings/qpid/ruby/examples/spout.rb
@@ -100,7 +100,7 @@ end
 # now get the non-arg options
 options[:address] = ARGV[0] unless ARGV[0].nil?
 
-connection = Qpid::Messaging::Connection.new options[:broker], options[:connection_options]
+connection = Qpid::Messaging::Connection.new :url => options[:broker], :options => options[:connection_options]
 connection.open
 session = connection.create_session
 sender = session.create_sender options[:address]
diff --git a/qpid/cpp/bindings/qpid/ruby/lib/qpid/connection.rb b/qpid/cpp/bindings/qpid/ruby/lib/qpid/connection.rb
index 5c56c1f5d0..915d635e53 100644
--- a/qpid/cpp/bindings/qpid/ruby/lib/qpid/connection.rb
+++ b/qpid/cpp/bindings/qpid/ruby/lib/qpid/connection.rb
@@ -23,56 +23,88 @@ module Qpid
 
   module Messaging
 
-    # Connection allows for establishing connections to a remote endpoint.
+    # Establishes a connection to a remote endpoint.
     class Connection
 
-      # The following general options are supported (as strings or symbols):
-      #
-      # username::
-      # password::
-      # heartbeat::
-      # tcp_nodelay::
-      # sasl_mechanism::
-      # sasl_service::
-      # sasl_min_ssf::
-      # sasl_max_ssf::
-      # transport::
-      #
-      # The following options specifically control reconnection behavior:
-      #
-      # reconnect:: *true* or *false*; indicates whether to attempt reconnections
-      # reconnect_timeout:: the number of seconds to attempt reconnecting
-      # reconnect_limit:: the number of retries before reporting failure
-      # reconnect_interval_min:: initial delay, in seconds, before attempting a reconnecting
-      # reconnect_interval_max:: number of seconds to wait before additional reconnect attempts
-      # reconnect_interval:: shorthand for setting box min and max values
-      # reconnect_urls:: a list of alternate URLs to use for reconnection attempts
-      def initialize(url, options = {}, connection_impl = nil)
-        @url = url
-        @connection_impl = connection_impl
-        @options = options
+      # Creates a connection object, but does not actually connect to
+      # the specified location.
+      #
+      # ==== Options
+      #
+      #   :url - the URL for the broker (def. +"localhost"+)
+      #   :options - connection options (def. +{}+)
+      #
+      # ==== Controlling Reconnect Behavior
+      #
+      # The following connection options can be used to configure
+      # the reconnection behavior for this connection.
+      #
+      # * :username
+      # * :password
+      # * :heartbeat
+      # * :tcp_nodelay
+      # * :sasl_mechanism
+      # * :sasl_service
+      # * :sasl_min_ssf
+      # * :sasl_max_ssf
+      # * :transport
+      # * :reconnect - +true+ or +false+; indicates wehtehr to attempt reconnections
+      # * :reconnect_timeout - the number of seconds to attempt reconnecting
+      # * :reconnect_limit - the number of retries before reporting failure
+      # * :reconnect_interval_min - initial delay, in seconds, before attempting a reconnection
+      # * :reconnect_interval_max - number of seconds to wait before additional reconnect attempts
+      # * :reconnect_interval - shorthand for setting both min and max values
+      # * :reconnect_urls - a list of alternate URLs to use for reconnection attempts
+      #
+      # ==== Examples
+      #
+      #   conn = Qpid::Messaging::Connnection.new
+      #   conn = Qpid::Messaging::Connection.new :url => "amqp:tcp:broker1.domain.com:5672"
+      #   conn = Qpid::Messaging::Connection.new :options => {:username => "login", :password => "password"}
+      #
+      def initialize(opts = {})
+        @url = opts[:url] || "localhost"
+        @options = opts[:options] || {}
+        @connection_impl = opts[:impl] || Cqpid::Connection.new(@url, convert_options)
       end
 
       def connection_impl # :nodoc:
         @connection_impl
       end
 
-      # Opens the connection.
+      # Establishes the connection.
+      #
+      # ==== Examples
+      #
+      #   conn.open unless conn.open?
+      #
       def open
-        @connection_impl = Cqpid::Connection.new(@url, convert_options)
         @connection_impl.open
       end
 
       # Reports whether the connection is open.
-      def open?; false || (@connection_impl.isOpen if @connection_impl); end
+      #
+      # ==== Examples
+      #
+      #   conn.close if conn.open?
+      #
+      def open?; true && !@connection_impl.nil? && @connection_impl.isOpen; end
 
       # Closes the connection.
-      def close; @connection_impl.close if open?; end
+      def close; @connection_impl.close; end
 
       # Creates a new session.
       #
-      # If :transactional => true then a transactional session is created.
-      # Otherwise a standard session is created.
+      # ==== Arguments
+      #
+      # * :name - specifies the name for this session
+      # * :transactional - if +true+ then a creates a transaction session (def. +false+)
+      #
+      # ==== Examples
+      #
+      #   session = conn.create_session :name => "session1"
+      #   session = conn.create_session :transaction => true
+      #
       def create_session(args = {})
         name = args[:name] || ""
         if open?
@@ -88,9 +120,22 @@ module Qpid
       end
 
       # Returns a session for the specified session name.
+      #
+      # ==== Examples
+      #
+      #   begin
+      #     session = conn.session "mysession"
+      #   rescue SessionNameException => error
+      #      puts "No such session."
+      #   end
+      #
       def session name
-        session_impl = @connection_impl.getSession name
-        Qpid::Messaging::Session.new session_impl if session_impl
+        begin
+          session_impl = @connection_impl.getSession name
+          Qpid::Messaging::Session.new session_impl if session_impl
+        rescue
+          raise Qpid::Messaging::SessionNameException.new "No such session: #{name}"
+        end
       end
 
       # Returns the username used to authenticate with the connection.
@@ -117,8 +162,6 @@ module Qpid
 
       def convert_options
         result = {}
-        # map only those options defined in the C++ layer
-        # TODO when new options are added, this needs to be updated.
         unless @options.nil? || @options.empty?
           @options.each_pair {|key, value| result[key.to_s] = value.to_s}
         end
diff --git a/qpid/cpp/bindings/qpid/ruby/lib/qpid/errors.rb b/qpid/cpp/bindings/qpid/ruby/lib/qpid/errors.rb
index 7a16d08d84..c98eb1ac12 100644
--- a/qpid/cpp/bindings/qpid/ruby/lib/qpid/errors.rb
+++ b/qpid/cpp/bindings/qpid/ruby/lib/qpid/errors.rb
@@ -21,7 +21,10 @@ module Qpid
 
   module Messaging
 
-    class KeyError < RuntimeError
+    class KeyError < RuntimeError; end
+
+    class SessionNameException < Exception
+      def initialize(msg); super(msg); end
     end
 
   end
diff --git a/qpid/cpp/bindings/qpid/ruby/lib/qpid/session.rb b/qpid/cpp/bindings/qpid/ruby/lib/qpid/session.rb
index 543c26cc70..f916b1518e 100644
--- a/qpid/cpp/bindings/qpid/ruby/lib/qpid/session.rb
+++ b/qpid/cpp/bindings/qpid/ruby/lib/qpid/session.rb
@@ -39,7 +39,7 @@ module Qpid
       # Returns the +Connection+ for the +Session+.
       def connection
         connection_impl = @session_impl.getConnection
-        Qpid::Messaging::Connection.new "", {}, connection_impl
+        Qpid::Messaging::Connection.new :impl => connection_impl
       end
 
       # Creates a new endpoint for sending messages.
diff --git a/qpid/cpp/bindings/qpid/ruby/test/test_connection.rb b/qpid/cpp/bindings/qpid/ruby/test/test_connection.rb
index 648fb0588a..936d8389d8 100644
--- a/qpid/cpp/bindings/qpid/ruby/test/test_connection.rb
+++ b/qpid/cpp/bindings/qpid/ruby/test/test_connection.rb
@@ -39,10 +39,22 @@ class TestConnection < Test::Unit::TestCase
     @url     = "localhost"
     @options = {}
 
-    @connection = Qpid::Messaging::Connection.new(@url, @options, @connection_impl)
+    @connection = Qpid::Messaging::Connection.new :url => @url, :options => @options, :impl => @connection_impl
   end
 
-  def test_create_with_username_and_password
+  def test_initialize
+    @cqpid_connection.
+      should_receive(:new).
+      once.
+      with("localhost", {}).
+      and_return(@connection_impl)
+
+    result = Qpid::Messaging::Connection.new
+
+    assert_same @connection_impl, result.connection_impl
+  end
+
+  def test_initialize_with_username_and_password
     @cqpid_connection.
       should_receive(:new).
       once.with("localhost",
@@ -53,26 +65,23 @@ class TestConnection < Test::Unit::TestCase
       should_receive(:open).
       once
 
-    result = Qpid::Messaging::Connection.new("localhost",
-                                             :username => "username",
-                                             :password => "password")
+    result = Qpid::Messaging::Connection.new(:name => "localhost",
+                                             :options => {
+                                               :username => "username",
+                                               :password => "password"
+                                             })
     result.open
 
     assert_same @connection_impl, result.connection_impl
   end
 
-  def test_create_with_hostname
+  def test_initialize_with_hostname
     result = Qpid::Messaging::Connection.new("localhost")
 
     assert_not_nil result
   end
 
   def test_open
-    @cqpid_connection.
-      should_receive(:new).
-      once.
-      with(@url, {}).
-      and_return(@connection_impl)
     @connection_impl.
       should_receive(:open).
       once
@@ -106,22 +115,9 @@ class TestConnection < Test::Unit::TestCase
     assert !@connection.open?
   end
 
-  def test_close_an_unopened_session
-    @connection_impl.
-      should_receive(:isOpen).
-      once.
-      and_return(false)
-
-    @connection.close
-  end
-
   def test_close
     @connection_impl.
-      should_receive(:isOpen).
-      once.
-      and_return(true).
-      should_receive(:close).
-      once
+      should_receive(:close)
 
     @connection.close
   end
@@ -240,6 +236,15 @@ class TestConnection < Test::Unit::TestCase
     assert !@connection.null?
   end
 
+  def test_session_with_invalid_session
+    @connection_impl.
+      should_receive(:getSession).
+      with("farkle").
+      and_raise(::RuntimeError)
+
+    assert_raise(Qpid::Messaging::SessionNameException) {@connection.session "Farkle"}
+  end
+
   def test_swap
     @other_connection.
       should_receive(:connection_impl).