QPID-3306 - Provides a more Ruby-like set of APIs on top of the bindings created by swig.

Applied patch from Darryl Pierce

Created the Connection class and its unit tests.

The Connection class is packaged as follows:

Qpid::Messaging::Connection


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

4 files changed, 393 insertions, 0 deletions

diff --git a/cpp/bindings/qpid/ruby/lib/qpid.rb b/cpp/bindings/qpid/ruby/lib/qpid.rb
index 65e6393bbe..1f00c136c1 100644
--- a/cpp/bindings/qpid/ruby/lib/qpid.rb
+++ b/cpp/bindings/qpid/ruby/lib/qpid.rb
@@ -25,4 +25,5 @@ require 'qpid/message'
 require 'qpid/sender'
 require 'qpid/receiver'
 require 'qpid/session'
+require 'qpid/connection'
 
diff --git a/cpp/bindings/qpid/ruby/lib/qpid/connection.rb b/cpp/bindings/qpid/ruby/lib/qpid/connection.rb
new file mode 100644
index 0000000000..5c56c1f5d0
--- /dev/null
+++ b/cpp/bindings/qpid/ruby/lib/qpid/connection.rb
@@ -0,0 +1,134 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+require 'cqpid'
+
+module Qpid
+
+  module Messaging
+
+    # Connection allows for establishing connections 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
+      end
+
+      def connection_impl # :nodoc:
+        @connection_impl
+      end
+
+      # Opens the connection.
+      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
+
+      # Closes the connection.
+      def close; @connection_impl.close if open?; end
+
+      # Creates a new session.
+      #
+      # If :transactional => true then a transactional session is created.
+      # Otherwise a standard session is created.
+      def create_session(args = {})
+        name = args[:name] || ""
+        if open?
+          if args[:transactional]
+            session = @connection_impl.createTransactionalSession name
+          else
+            session = @connection_impl.createSession name
+          end
+          return Session.new(session)
+        else
+          raise RuntimeError.new "No connection available."
+        end
+      end
+
+      # Returns a session for the specified session name.
+      def session name
+        session_impl = @connection_impl.getSession name
+        Qpid::Messaging::Session.new session_impl if session_impl
+      end
+
+      # Returns the username used to authenticate with the connection.
+      def authenticated_username; @connection_impl.getAuthenticatedUsername if open?; end
+
+      # inherited from Handle
+
+      # Returns whether the underlying handle is valid; i.e., not null.
+      def valid?
+        @connection_impl.isValid
+      end
+
+      # Returns whether the underlying handle is null.
+      def null?
+        @connection_impl.isNull
+      end
+
+      # Swaps the underlying connection handle.
+      def swap connection
+        @connection_impl.swap connection.connection_impl
+      end
+
+      private
+
+      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
+
+        return result
+      end
+
+    end
+
+  end
+
+end
+
diff --git a/cpp/bindings/qpid/ruby/test/test_connection.rb b/cpp/bindings/qpid/ruby/test/test_connection.rb
new file mode 100644
index 0000000000..648fb0588a
--- /dev/null
+++ b/cpp/bindings/qpid/ruby/test/test_connection.rb
@@ -0,0 +1,257 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+
+require 'test/unit'
+require 'flexmock/test_unit'
+
+require 'cqpid'
+require 'qpid/connection'
+
+class TestConnection < Test::Unit::TestCase
+
+  def setup
+    @connection_impl       = flexmock("connection_impl")
+    @other_connection      = flexmock("other_connection")
+    @other_connection_impl = flexmock("other_connection_impl")
+    @cqpid_connection      = flexmock(Cqpid::Connection)
+
+    @session      = flexmock("session")
+    @session_name = "test-session"
+
+    @url     = "localhost"
+    @options = {}
+
+    @connection = Qpid::Messaging::Connection.new(@url, @options, @connection_impl)
+  end
+
+  def test_create_with_username_and_password
+    @cqpid_connection.
+      should_receive(:new).
+      once.with("localhost",
+                {"username" => "username",
+                  "password" => "password"}).
+      and_return(@connection_impl)
+    @connection_impl.
+      should_receive(:open).
+      once
+
+    result = Qpid::Messaging::Connection.new("localhost",
+                                             :username => "username",
+                                             :password => "password")
+    result.open
+
+    assert_same @connection_impl, result.connection_impl
+  end
+
+  def test_create_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
+
+    @connection.open
+
+    assert_same @connection_impl, @connection.connection_impl
+  end
+
+  def test_check_open_when_open
+    @connection_impl.
+      should_receive(:isOpen).
+      once.
+      and_return(true)
+
+    assert @connection.open?
+  end
+
+  def test_check_open_before_connection
+    result = Qpid::Messaging::Connection.new("hostname")
+
+    assert !result.open?
+  end
+
+  def test_check_open_when_closed
+    @connection_impl.
+      should_receive(:isOpen).
+      once.
+      and_return(false)
+
+    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
+
+    @connection.close
+  end
+
+  def test_create_session_without_name
+    @connection_impl.
+      should_receive(:isOpen).
+      once.
+      and_return(true).
+      should_receive(:createSession).
+      once.
+      with("").
+      and_return(@session)
+
+    result = @connection.create_session
+
+    assert_not_nil result
+    assert_same @session, result.session_impl
+  end
+
+  def test_create_session
+    @connection_impl.
+      should_receive(:isOpen).
+      once.
+      and_return(true).
+      should_receive(:createSession).
+      once.
+      with(@session_name).
+      and_return(@session)
+
+    result = @connection.create_session :name => @session_name
+
+    assert_not_nil result
+    assert_same @session, result.session_impl
+  end
+
+  def test_create_session_raises_exception_when_closed
+    @connection_impl.
+      should_receive(:isOpen).
+      once.
+      and_return(false)
+
+    assert_raise(RuntimeError) {@connection.create_session @session_name}
+  end
+
+  def test_create_transactional_session
+    @connection_impl.
+      should_receive(:isOpen).
+      once.
+      and_return(true).
+      should_receive(:createTransactionalSession).
+      once.
+      with("").
+      and_return(@session)
+
+    result = @connection.create_session :transactional => true
+
+    assert_not_nil result
+    assert_same @session, result.session_impl
+  end
+
+  def test_authenticated_username_when_not_connected
+    @connection_impl.
+      should_receive(:isOpen).
+      once.
+      and_return(false)
+
+    result = @connection.authenticated_username
+
+    assert_nil result
+  end
+
+  def test_authenticated_username
+    @connection_impl.
+      should_receive(:isOpen).
+      once.
+      and_return(true).
+      should_receive(:getAuthenticatedUsername).
+      once.
+      and_return("farkle")
+
+    result = @connection.authenticated_username
+
+    assert_equal "farkle", result
+  end
+
+  def test_get_session_with_invalid_name
+    @connection_impl.
+      should_receive(:getSession).
+      once.
+      with(@session_name).
+      and_return(nil)
+
+    result = @connection.session @session_name
+
+    assert_nil result
+  end
+
+  # APIs inherited from Handle
+
+  def test_is_valid
+    @connection_impl.
+      should_receive(:isValid).
+      once.
+      and_return(true)
+
+    assert @connection.valid?
+  end
+
+  def test_is_null
+    @connection_impl.
+      should_receive(:isNull).
+      once.
+      and_return(false)
+
+    assert !@connection.null?
+  end
+
+  def test_swap
+    @other_connection.
+      should_receive(:connection_impl).
+      once.
+      and_return(@other_connection_impl)
+    @connection_impl.
+      should_receive(:swap).
+      once.
+      with(@other_connection_impl)
+
+    @connection.swap @other_connection
+  end
+
+end
+
diff --git a/cpp/bindings/qpid/ruby/test/ts_bindings.rb b/cpp/bindings/qpid/ruby/test/ts_bindings.rb
index 4d3b906ffc..7aa410c8f8 100644
--- a/cpp/bindings/qpid/ruby/test/ts_bindings.rb
+++ b/cpp/bindings/qpid/ruby/test/ts_bindings.rb
@@ -26,4 +26,5 @@ require 'test_message'
 require 'test_sender'
 require 'test_receiver'
 require 'test_session'
+require 'test_connection'