data_objects 0.9.11 → 0.9.12

data/lib/data_objects/reader.rb

@@ -1,30 +1,31 @@
 module DataObjects
+  # Abstract class to read rows from a query result
   class Reader
 
+    # Return the array of field names
     def fields
       raise NotImplementedError.new
     end
 
+    # Return the array of field values for the current row. Not legal after next! has returned false or before it's been called
     def values
       raise NotImplementedError.new
     end
 
+    # Close the reader discarding any unread results.
     def close
       raise NotImplementedError.new
     end
 
-    # Moves the cursor forward.
+    # Discard the current row (if any) and read the next one (returning true), or return nil if there is no further row.
     def next!
       raise NotImplementedError.new
     end
 
+    # Return the number of fields in the result set.
     def field_count
       raise NotImplementedError.new
     end
 
-    def row_count
-      raise NotImplementedError.new
-    end
-
   end
 end

data/lib/data_objects/result.rb

@@ -1,11 +1,17 @@
 module DataObjects
+  # The Result class is returned from Connection#execute_non_query.
   class Result
-    attr_accessor :insert_id, :affected_rows
+    # The ID of a row inserted by the Command
+    attr_accessor :insert_id
+    # The number of rows affected by the Command
+    attr_accessor :affected_rows
 
+    # Create a new Result. Used internally in the adapters.
     def initialize(command, affected_rows, insert_id = nil)
       @command, @affected_rows, @insert_id = command, affected_rows, insert_id
     end
 
+    # Return the number of affected rows
     def to_i
       @affected_rows
     end

data/lib/data_objects/spec/command_spec.rb

@@ -0,0 +1,191 @@
+WINDOWS = Gem.win_platform?
+
+share_examples_for 'a Command' do
+
+  include DataObjectsSpecHelpers
+
+  before :all do
+    setup_test_environment
+  end
+
+  before :each do
+    @connection = DataObjects::Connection.new(CONFIG.uri)
+    @command    = @connection.create_command("INSERT INTO users (name) VALUES (?)")
+    @reader     = @connection.create_command("SELECT code, name FROM widgets WHERE ad_description = ?")
+  end
+
+  after :each do
+    @connection.close
+  end
+
+  it { @command.should be_kind_of(DataObjects::Command) }
+
+  it { @command.should respond_to(:execute_non_query) }
+
+  describe 'execute_non_query' do
+
+    describe 'with an invalid statement' do
+
+      before :each do
+        @invalid_command = @connection.create_command("INSERT INTO non_existent_table (tester) VALUES (1)")
+      end
+
+      it 'should raise an error on an invalid query' do
+        lambda { @invalid_command.execute_non_query }.should raise_error
+      end
+
+      it 'should raise an error with too few binding parameters' do
+        lambda { @command.execute_non_query("Too", "Many") }.should raise_error(ArgumentError, "Binding mismatch: 2 for 1")
+      end
+
+      it 'should raise an error with too many binding parameters' do
+        lambda { @command.execute_non_query }.should raise_error(ArgumentError, "Binding mismatch: 0 for 1")
+      end
+
+    end
+
+    describe 'with a valid statement' do
+
+      it 'should not raise an error with an explicit nil as parameter' do
+        lambda { @command.execute_non_query(nil) }.should_not raise_error
+      end
+
+    end
+
+  end
+
+  it { @command.should respond_to(:execute_reader) }
+
+  describe 'execute_reader' do
+
+    describe 'with an invalid reader' do
+
+      before :each do
+        @invalid_reader = @connection.create_command("SELECT * FROM non_existent_widgets WHERE ad_description = ?")
+      end
+
+      it 'should raise an error on an invalid query' do
+        lambda { @invalid_reader.execute_reader }.should raise_error
+      end
+
+      it 'should raise an error with too few binding parameters' do
+        lambda { @reader.execute_reader("Too", "Many") }.should raise_error(ArgumentError, "Binding mismatch: 2 for 1")
+      end
+
+      it 'should raise an error with too many binding parameters' do
+        lambda { @reader.execute_reader }.should raise_error(ArgumentError, "Binding mismatch: 0 for 1")
+      end
+
+    end
+
+    describe 'with a valid reader' do
+
+      it 'should not raise an error with an explicit nil as parameter' do
+        lambda { @reader.execute_reader(nil) }.should_not raise_error
+      end
+
+    end
+
+  end
+
+  it { @command.should respond_to(:set_types) }
+
+  describe 'set_types' do
+
+    describe 'is invalid when used with a statement' do
+
+      before :each do
+        @command.set_types(String)
+      end
+
+      it 'should raise an error when types are set' do
+        lambda { @command.execute_non_query }.should raise_error
+      end
+
+    end
+
+    describe 'with an invalid reader' do
+
+      it 'should raise an error with too few types' do
+        @reader.set_types(String)
+        lambda { @reader.execute_reader("One parameter") }.should raise_error(ArgumentError, "Field-count mismatch. Expected 1 fields, but the query yielded 2")
+      end
+
+      it 'should raise an error with too many types' do
+        @reader.set_types(String, String, BigDecimal)
+        lambda { @reader.execute_reader("One parameter") }.should raise_error(ArgumentError, "Field-count mismatch. Expected 3 fields, but the query yielded 2")
+      end
+
+    end
+
+    describe 'with a valid reader' do
+
+      it 'should not raise an error with correct number of types' do
+        @reader.set_types(String, String)
+        lambda { @result = @reader.execute_reader('Buy this product now!') }.should_not raise_error
+        lambda { @result.next! }.should_not raise_error
+        lambda { @result.values }.should_not raise_error
+        @result.close
+      end
+
+      it 'should also support old style array argument types' do
+        @reader.set_types([String, String])
+        lambda { @result = @reader.execute_reader('Buy this product now!') }.should_not raise_error
+        lambda { @result.next! }.should_not raise_error
+        lambda { @result.values }.should_not raise_error
+        @result.close
+      end
+
+    end
+
+  end
+
+  it { @command.should respond_to(:to_s) }
+
+  describe 'to_s' do
+
+  end
+
+
+end
+
+share_examples_for 'a Command with async' do
+
+  include DataObjectsSpecHelpers
+
+  before :all do
+    setup_test_environment
+  end
+
+  describe 'running queries in parallel' do
+
+    before :each do
+
+      threads = []
+
+      @start = Time.now
+      4.times do |i|
+        threads << Thread.new do
+          connection = DataObjects::Connection.new(CONFIG.uri)
+          command = connection.create_command(CONFIG.sleep)
+          result = command.execute_non_query
+          connection.close
+        end
+      end
+
+      threads.each{|t| t.join }
+      @finish = Time.now
+    end
+
+    after :each do
+      @connection.close
+    end
+
+    it "should finish within 2 seconds" do
+      pending_if("Ruby on Windows doesn't support asynchronious operations", WINDOWS) do
+        (@finish - @start).should < 2
+      end
+    end
+
+  end
+end

data/lib/data_objects/spec/connection_spec.rb

@@ -0,0 +1,106 @@
+share_examples_for 'a Connection' do
+
+  include DataObjectsSpecHelpers
+
+  before :all do
+    setup_test_environment
+  end
+
+  before :each do
+    @connection = DataObjects::Connection.new(CONFIG.uri)
+  end
+
+  after :each do
+    @connection.close
+  end
+
+  it { @connection.should be_kind_of(DataObjects::Connection) }
+  it { @connection.should be_kind_of(Extlib::Pooling) }
+
+  it { @connection.should respond_to(:dispose) }
+
+  describe 'dispose' do
+
+    describe 'on open connection' do
+      before do
+        @open_connection = DataObjects::Connection.new("#{@driver}://#{@user}:#{@password}@#{@host}:#{@port}#{@database}")
+        @open_connection.detach
+      end
+
+      after do
+        @open_connection.close
+      end
+
+      it { @open_connection.dispose.should be_true }
+    end
+
+    describe 'on closed connection' do
+      before do
+        @closed_connection = DataObjects::Connection.new("#{@driver}://#{@user}:#{@password}@#{@host}:#{@port}#{@database}")
+        @closed_connection.detach
+        @closed_connection.dispose
+      end
+
+      after do
+        @closed_connection.close
+      end
+
+      it { @closed_connection.dispose.should be_false }
+
+      it 'should raise an error on creating a command' do
+        lambda { @closed_connection.create_command("INSERT INTO non_existant_table (tester) VALUES (1)").execute_non_query }.should raise_error
+      end
+    end
+
+  end
+
+  it { @connection.should respond_to(:create_command) }
+
+  describe 'create_command' do
+    it { @connection.create_command('This is a dummy command').should be_kind_of(DataObjects::Command) }
+  end
+
+end
+
+share_examples_for 'a Connection with authentication support' do
+
+  before :all do
+    %w[ @driver @user @password @host @port @database ].each do |ivar|
+      raise "+#{ivar}+ should be defined in before block" unless instance_variable_get(ivar)
+    end
+
+  end
+
+  describe 'with an invalid URI' do
+
+    def connecting_with(uri)
+      lambda { DataObjects::Connection.new(uri) }
+    end
+
+    it 'should raise an error if no database specified' do
+      connecting_with("#{@driver}://#{@user}:#{@password}@#{@host}:#{@port}").should raise_error
+    end
+
+    it 'should raise an error if bad username is given' do
+      connecting_with("#{@driver}://thisreallyshouldntexist:#{@password}@#{@host}:#{@port}#{@database}").should raise_error
+    end
+
+    it 'should raise an error if bad password is given' do
+      connecting_with("#{@driver}://#{@user}:completelyincorrectpassword:#{@host}:#{@port}#{@database}").should raise_error
+    end
+
+    it 'should raise an error if an invalid port is given' do
+      connecting_with("#{@driver}://#{@user}:#{@password}:#{@host}:648646543#{@database}").should raise_error
+    end
+
+    it 'should raise an error if an invalid database is given' do
+      connecting_with("#{@driver}://#{@user}:#{@password}:#{@host}:#{@port}/someweirddatabase").should raise_error
+    end
+
+    it 'should raise an error with a meaningless URI' do
+      connecting_with("#{@driver}://peekaboo$2!@#4543").should raise_error
+    end
+
+  end
+
+end

data/lib/data_objects/spec/encoding_spec.rb

@@ -0,0 +1,31 @@
+share_examples_for 'a driver supporting encodings' do
+
+  before :each do
+    @connection = DataObjects::Connection.new(CONFIG.uri)
+  end
+
+  after :each do
+    @connection.close
+  end
+
+
+  it { @connection.should respond_to(:character_set) }
+
+  describe 'character_set' do
+
+    it 'uses utf8 by default' do
+      @connection.character_set.should == 'utf8'
+    end
+
+    describe 'sets the character set through the URI' do
+      before do
+        @latin1_connection = DataObjects::Connection.new("#{CONFIG.scheme}://#{CONFIG.user}:#{CONFIG.pass}@#{CONFIG.host}:#{CONFIG.port}#{CONFIG.database}?encoding=latin1")
+      end
+
+      after { @latin1_connection.close }
+
+      it { @latin1_connection.character_set.should == 'latin1' }
+    end
+
+  end
+end

data/lib/data_objects/spec/reader_spec.rb

@@ -0,0 +1,156 @@
+share_examples_for 'a Reader' do
+
+  include DataObjectsSpecHelpers
+
+  before :all do
+    setup_test_environment
+  end
+
+  before :each do
+    @connection = DataObjects::Connection.new(CONFIG.uri)
+    @reader     = @connection.create_command("SELECT code, name FROM widgets WHERE ad_description = ? order by id").execute_reader('Buy this product now!')
+  end
+
+  after :each do
+    @reader.close
+    @connection.close
+  end
+
+  it { @reader.should respond_to(:fields) }
+
+  describe 'fields' do
+
+    it 'should return the correct fields in the reader' do
+      # we downcase the field names as some drivers such as do_derby, do_h2,
+      # do_hsqldb return the field names as uppercase
+      @reader.fields.map{ |f| f.downcase }.should == ['code', 'name']
+    end
+
+  end
+
+  it { @reader.should respond_to(:values) }
+
+  describe 'values' do
+
+    describe 'when the reader is uninitialized' do
+
+      it 'should raise an error' do
+        lambda { @reader.values }.should raise_error
+      end
+
+    end
+
+    describe 'when the reader is moved to the first result' do
+
+      before  do
+        @reader.next!
+      end
+
+      it 'should return the correct first set of in the reader' do
+        @reader.values.should == ["W0000001", "Widget 1"]
+      end
+
+    end
+
+    describe 'when the reader is moved to the second result' do
+
+      before  do
+        @reader.next!; @reader.next!
+      end
+
+      it 'should return the correct first set of in the reader' do
+        @reader.values.should == ["W0000002", "Widget 2"]
+      end
+
+    end
+
+    describe 'when the reader is moved to the end' do
+
+      before do
+        while @reader.next! ; end
+      end
+
+      it 'should raise an error again' do
+        lambda { @reader.values }.should raise_error
+      end
+    end
+
+  end
+
+  it { @reader.should respond_to(:close) }
+
+  describe 'close' do
+
+    describe 'on an open reader' do
+
+      it 'should return true' do
+        @reader.close.should be_true
+      end
+
+    end
+
+    describe 'on an already closed reader' do
+
+      before do
+        @reader.close
+      end
+
+      it 'should return false' do
+        @reader.close.should be_false
+      end
+
+    end
+
+  end
+
+  it { @reader.should respond_to(:next!) }
+
+  describe 'next!' do
+
+    describe 'successfully moving the cursor initially' do
+
+      it 'should return true' do
+        @reader.next!.should be_true
+      end
+
+    end
+
+    describe 'moving the cursor' do
+
+      before do
+        @reader.next!
+      end
+
+      it 'should move the cursor to the next value' do
+        lambda { @reader.next! }.should change(@reader, :values).
+                                          from(["W0000001", "Widget 1"]).
+                                            to(["W0000002", "Widget 2"])
+      end
+
+    end
+
+    describe 'arriving at the end of the reader' do
+
+      before do
+        while @reader.next!; end
+      end
+
+      it 'should return false when the end is reached' do
+        @reader.next!.should be_false
+      end
+
+    end
+
+  end
+
+  it { @reader.should respond_to(:field_count) }
+
+  describe 'field_count' do
+
+    it 'should count the number of fields' do
+      @reader.field_count.should == 2
+    end
+
+  end
+
+end