simpleOracleJDBC 0.1

data/lib/simple_oracle_jdbc/result_set.rb

@@ -0,0 +1,155 @@
+module SimpleOracleJDBC
+
+  # This module provides a wrapper around a JDBC result set object, allowing the result set to be returned
+  # a row at a time, as an array or arrays or an array of hashes etc.
+  #
+  # Requires a instance variable called @result_set to be defined in the class
+  # this module is included into. This should contain a JDBC result set object.
+
+  module ResultSet
+
+    # Retrieves the next row from the database and returns an array. Each element in the array
+    # corresponds to a column in the select statement that created the result set.
+    #
+    # The value nil will be returned if there are no more rows to return, and the result set
+    # will be closed.
+    def next_array
+      next_row
+    end
+
+    # Processes each row of the result set using the provided block, passing one row at a time
+    # to the block as an array, eg:
+    #
+    #    obj.each_array do |r|
+    #      # process the row
+    #    end
+    #
+    # The result set will be closed when the method returns.
+    def each_array(&blk)
+      each_result true, &blk
+    end
+
+    # Consumes all the rows of the result set, and returns the result as an array of arrays.
+    #
+    # An empty array will be returned if the result set contains no rows.
+    #
+    # If the result set contains a lot of rows, this will create an array that requires a lot of
+    # memory, so use with caution.
+    #
+    # The result set will be closed when the method returns.
+    def all_array
+      all_results(true)
+    end
+
+    # Similar to next_array, only it returns the result as a hash. The hash will have one key
+    # for each column in the corresponding select statement. The key will be the upper case name of
+    # the column or alias from the SQL statement.
+    def next_hash
+      next_row(false)
+    end
+
+    # Processes each row of the result set using hte provided block, passing one row as a time to
+    # the block as a hash, eg:
+    #
+    #    obj.each_hash do |r|
+    #      # process the row
+    #    end
+    #
+    # The result set will be closed when the method returns.
+    def each_hash(&blk)
+      each_result false, &blk
+    end
+
+    # Consumes all the rows of the result set, and returns the result as an array of hashes.
+    #
+    # An empty array will be returned if the result set contains no rows.
+    #
+    # If the result set contains a lot of rows, this will create an array that requires a lot of
+    # memory, so use with caution.
+    #
+    # The result set will be closed when the method returns.
+    def all_hash
+      all_results(false)
+    end
+
+    # Closes the result set if it exists, and also closes the SQL statement that created the result
+    # set.
+    # TODO - does it make sense to close the statement here too?
+    def close_result_set
+      if @result_set
+        @result_set.close
+        @result_set = nil
+      end
+      close_statement
+    end
+
+    private
+
+    def row_as_array
+      cols = @result_set.get_meta_data.get_column_count
+      a = Array.new
+      1.upto(cols) do |i|
+        a.push retrieve_value(@result_set, i)
+      end
+      a
+    end
+
+    def row_as_hash
+      mdata = @result_set.get_meta_data
+      cols = mdata.get_column_count
+      h = Hash.new
+      1.upto(cols) do |i|
+        h[mdata.get_column_name(i)] = retrieve_value(@result_set, i)
+      end
+      h
+    end
+
+    def all_results(array=true)
+      raise SimpleOracleJDBC::NoResultSet unless @result_set
+      results = Array.new
+      begin
+        while(r = @result_set.next) do
+          if array
+            results.push row_as_array
+          else
+            results.push row_as_hash
+          end
+        end
+      ensure
+        close_result_set
+      end
+      results
+    end
+
+    def each_result(as_array=true, &blk)
+      raise SimpleOracleJDBC::NoResultSet unless @result_set
+      begin
+        while(r = @result_set.next)
+          if as_array
+            yield row_as_array
+          else
+            yield row_as_hash
+          end
+        end
+      ensure
+        close_result_set
+      end
+    end
+
+    def next_row(as_array=true)
+      raise SimpleOracleJDBC::NoResultSet unless @result_set
+      r = @result_set.next
+      if r
+        if as_array
+          row_as_array
+        else
+          row_as_hash
+        end
+      else
+        close_result_set
+        nil
+      end
+    end
+
+  end
+end

data/lib/simple_oracle_jdbc/sql.rb

@@ -0,0 +1,95 @@
+module SimpleOracleJDBC
+
+  class Sql
+
+    # The Sql class provides a simple interface for preparing, executing and retrieving results
+    # for SQL statements.
+    #
+    # The ResultSet module is included to allow results to be retrieved from result sets as arrays
+    # or hashes.
+    #
+    # The Binding module is included to allow Ruby types to be convered into sensible Java equivalents
+    # and vice versa.
+    #
+    # @!attribute statement
+    #   @return [JDBC Prepared Statement] Returns the raw JDBC prepared statement
+    #
+    # @!attribute sql
+    #   @return [String] Returns the original SQL string used to create the object
+    #
+    # @!attribute result_set
+    #   @return [JDBC Result Set] Returns the raw JDBC result set after the statement is executed
+
+
+    include Binding
+    include ResultSet
+
+    attr_reader :statement, :sql, :result_set
+
+    attr_writer :result_set
+
+    # Creates a new instance of this class. Not intended to be used directly. Use the factory
+    # class methods prepare or execute instead.
+    def initialize
+    end
+
+    # Takes a JDBC connection object and an SQL statement and returns a SimpleOracleJDBC::Sql
+    # object with the prepared statement.
+    def self.prepare(connection, sql)
+      sql_object = self.new
+      sql_object.prepare(connection,sql)
+    end
+
+    # Takes a JDBC connection object, an SQL statement and an optional list of bind variables and
+    # will prepare and execute the sql statement, returning an SimpleOracle::Sql object.
+    def self.execute(connection, sql, *binds)
+      sql_object = self.new
+      sql_object.prepare(connection, sql)
+      sql_object.execute(*binds)
+    end
+
+    # Given a JDBC connection and a SQL string, the sql will be stored in the @sql instance variable
+    # and a JDBC prepared statement will be stored in @statement.
+    #
+    # This method returns self to allow calls to be chained.
+    def prepare(connection, sql)
+      @sql = sql
+      @statement = connection.prepare_statement(@sql)
+      self
+    end
+
+    # Executes the SQL prepared by the prepare method and binds the optional list of bind varibles.
+    #
+    # If the SQL statement does not return data (ie is not a select statement) then @result_set will be
+    # set to nil. Otherwise, the resulting JDBC result set will be stored in @result_set
+    def execute(*binds)
+      binds.each_with_index do |b, i|
+        bind_value(@statement, b, i+1)
+      end
+
+      unless @sql =~ /^\s*select/i
+        @result_set = nil
+        @statement.execute()
+        close_statement
+      else
+        @result_set = @statement.execute_query()
+      end
+      self
+    end
+
+    # Closes both the prepared SQL statement stored in @statement and any result set stored in @result_set
+    def close
+      close_result_set
+      close_statement
+    end
+
+    # Closes the JDBC statement stored in @statement
+    def close_statement
+      if @statement
+        @statement.close
+        @statement = nil
+      end
+    end
+
+  end
+end

data/test/binding_test.rb

@@ -0,0 +1,224 @@
+require 'helper'
+
+class BindingTest < Test::Unit::TestCase
+
+  include TestHelper
+
+  def setup
+    @interface = @@interface
+    @sql = SimpleOracleJDBC::Sql.new
+  end
+
+  def teardown
+    @sql.close
+  end
+
+  # The binding module provides a set of methods to bind ruby
+  # types to SQL bindable objects (prepared proc calls or SQL statements)
+  # All it needs is a bindable object to be passed.
+  #
+  # For ease of testing, the ::Interface will be used to create the
+  # prepared objects.
+
+  def test_dates_can_be_bound_and_retrieved
+    call = @interface.prepare_proc("begin
+                                     :l_date := :i_date;
+                                   end;")
+    call.execute([Date, nil, :out], Date.new(2012,1,1))
+    assert_equal(Date.new(2012,1,1), call[1])
+    assert(call[1].is_a? Date)
+  end
+
+  def test_null_dates_can_be_bound_and_retrieved
+    call = @interface.prepare_proc("begin
+                                     :l_date := :i_date;
+                                   end;")
+    call.execute([Date, nil, :out], [Date, nil])
+    assert_nil(call[1])
+  end
+
+
+  def test_times_can_be_bound_and_retrieved
+    call = @interface.prepare_proc("begin
+                                     :l_date := :i_date;
+                                   end;")
+    t = Time.now
+    call.execute([Time, nil, :out], t)
+    assert_equal(t, call[1])
+    assert(call[1].is_a? Time)
+  end
+
+  def test_null_times_can_be_bound_and_retrieved
+    call = @interface.prepare_proc("begin
+                                     :l_date := :i_date;
+                                   end;")
+    call.execute([Time, nil, :out], [Time, nil])
+    assert_nil(call[1])
+  end
+
+  def test_string_can_be_bound_and_retrieved
+    call = @interface.prepare_proc("begin
+                                     :l_date := :i_date;
+                                   end;")
+    t = "hello there I am a string"
+    call.execute([String, nil, :out], t)
+    assert_equal(t, call[1])
+    assert(call[1].is_a? String)
+  end
+
+  def test_null_string_can_be_bound_and_retrieved
+    call = @interface.prepare_proc("begin
+                                     :l_date := :i_date;
+                                   end;")
+    call.execute([String, nil, :out], [String, nil])
+    assert_nil(call[1])
+  end
+
+  def test_integer_can_be_bound_and_retrieved
+    call = @interface.prepare_proc("begin
+                                     :l_date := :i_date;
+                                   end;")
+    t = 1234
+    call.execute([Integer, nil, :out], t)
+    assert_equal(t, call[1])
+    assert(call[1].is_a? Fixnum)
+  end
+
+  def test_null_integer_can_be_bound_and_retrieved
+    call = @interface.prepare_proc("begin
+                                     :l_date := :i_date;
+                                   end;")
+    call.execute([Integer, nil, :out], [Integer, nil])
+    assert_nil(call[1])
+  end
+
+  def test_number_can_be_bound_and_retrieved
+    call = @interface.prepare_proc("begin
+                                     :l_date := :i_date;
+                                   end;")
+    t = 1234.123456789
+    call.execute([Float, nil, :out], t)
+    assert_equal(t, call[1])
+    assert(call[1].is_a? Float)
+  end
+
+  def test_null_number_can_be_bound_and_retrieved
+    call = @interface.prepare_proc("begin
+                                     :l_date := :i_date;
+                                   end;")
+    call.execute([Float, nil, :out], [Float, nil])
+    assert_nil(call[1])
+  end
+
+  def test_refcursor_can_be_bound_and_retrieved
+    call = @interface.prepare_proc("declare
+                                      v_refcursor sys_refcursor;
+                                    begin
+                                      open v_refcursor for
+                                      select * from dual;
+
+                                      :ret := v_refcursor;
+                                    end;")
+    call.execute([:refcursor, nil, :out])
+    results = call[1]
+    assert(results.is_a? SimpleOracleJDBC::Sql)
+    rows = results.all_array
+    assert_equal(rows.length, 1)
+    assert_equal(rows[0][0], 'X')
+  end
+
+  def test_unknown_data_type_raises_exeception_when_bound
+    call = @interface.prepare_proc("begin
+                                     :l_date := :i_date;
+                                   end;")
+    assert_raises SimpleOracleJDBC::UnknownBindType do
+      call.execute([SimpleOracleJDBC::Interface, nil, :out], [Float, nil])
+    end
+  end
+
+  def test_in_out_parameter_can_be_bound
+    call = @interface.prepare_proc("begin
+                                     :l_date := :i_date;
+                                   end;")
+    t = 1234.123456789
+    call.execute([Float, nil, :out], [Float, t, :inout])
+    assert_equal(t, call[1])
+    assert(call[1].is_a? Float)
+  end
+
+  ### SQL specific tests.
+
+  def test_date_is_retrieved_as_ruby_time
+    sql = @interface.execute_sql("select to_date('20120713 13:23:23', 'YYYYMMDD HH24:MI:SS') from dual")
+    results = sql.all_array
+    assert_equal(results[0][0], Time.local(2012, 7, 13, 13, 23, 23))
+  end
+
+  def test_null_date_is_retrived_as_nil
+    sql = @interface.execute_sql("select cast(null as date) from dual")
+    results = sql.all_array
+    assert_equal(results[0][0], nil)
+  end
+
+  def test_timestamp_is_retrieved_as_ruby_time
+    sql = @interface.execute_sql("select cast(to_date('20120713 13:23:23', 'YYYYMMDD HH24:MI:SS') as timestamp) from dual")
+    results = sql.all_array
+    assert_equal(results[0][0], Time.local(2012, 7, 13, 13, 23, 23))
+  end
+
+  def test_null_timestamp_is_retrived_as_nil
+    sql = @interface.execute_sql("select cast(null as timestamp) from dual")
+    results = sql.all_array
+    assert_equal(results[0][0], nil)
+  end
+
+  def test_integer_is_retrieved_as_ruby_integer
+    sql = @interface.execute_sql("select cast(1234567890 as integer) from dual")
+    results = sql.all_array
+    assert_equal(results[0][0], 1234567890)
+  end
+
+  def test_null_integer_is_retrived_as_nil
+    sql = @interface.execute_sql("select cast(null as integer) from dual")
+    results = sql.all_array
+    assert_equal(results[0][0], nil)
+  end
+
+  def test_number_is_retrieved_as_ruby_float
+    sql = @interface.execute_sql("select cast(1234567890.123456789 as number) from dual")
+    results = sql.all_array
+    assert_equal(results[0][0], 1234567890.123456789)
+  end
+
+  def test_null_number_is_retrived_as_nil
+    sql = @interface.execute_sql("select cast(null as number) from dual")
+    results = sql.all_array
+    assert_equal(results[0][0], nil)
+  end
+
+  def test_char_is_retrieved_as_ruby_string
+    sql = @interface.execute_sql("select cast('hello there' as char(11)) from dual")
+    results = sql.all_array
+    assert_equal(results[0][0], "hello there")
+  end
+
+  def test_null_char_is_retrieved_as_nil
+    sql = @interface.execute_sql("select cast(null as char(10)) from dual")
+    results = sql.all_array
+    assert_equal(results[0][0], nil)
+  end
+
+  def test_varchar_is_retrieved_as_ruby_string
+    sql = @interface.execute_sql("select cast('hello there' as varchar2(1000)) from dual")
+    results = sql.all_array
+    assert_equal(results[0][0], "hello there")
+  end
+
+  def test_null_varchar_is_retrieved_as_nil
+    sql = @interface.execute_sql("select cast(null as varchar2(10)) from dual")
+    results = sql.all_array
+    assert_equal(results[0][0], nil)
+  end
+
+
+end