simpleOracleJDBC 0.1 → 0.1.1

data/README.md

@@ -1,64 +1,203 @@
-# Simple Oracle JDBC
+# A Thin Wrapper
 
-This gem provides a lightweight wrapper around a raw JDBC connection to make interaction between JRuby and Oracle easier. It only wraps commonly used features of JDBC, and makes the raw JDBC connection available to handle less common or more complex tasks.
+The idea behind this gem is that it provides a thin wrapper around a JDBC connection. It provides an interface to quickly execute SQL statements and stored procedures, but leaves the raw JDBC connection available if anything more complicated is required, such as binding array types.
 
-## Requirements
+Values can be bound to SQL statements and procedures by simple passing an array of Ruby types into the excecute call, and they are mapped automatically into the correct Java SQL types. The same happens when values are returned from procedures and queries.
+
+# More Than Just Testing
+
+While the gem was created to help with Unit Testing PLSQL code, there is nothing preventing it being used for other quick scripts or prototypes. I haven't looked at performance at all, so if you decided to use it in a production application, test it thoroughly first!
+
+# Requirements
 
 This gem will only work with JRuby as it uses the Java JDBC interface.
 
 The Oracle JDBC drivers (ojdbc6.jar) need to be in the JRuby lib directory.
 
-## Simple Usage
+# Usage
 
-The intended entry point is the Interface class. Various Interface methods will return Sql or DBCall objects. Note that the Sql and DBCall objects should generally be closed when they are no longer required to free up resources on the database.
+The best way to learn how to use Simple Oracle JDBC is to read through the sample code below, and then checkout the documentation.
 
-    require 'rubygems'
     require 'simple_oracle_jdbc'
-
-    @interface = SimpleOracleJDBC::Interface.create('sodonnel',
-                                                    'sodonnel',
-                                                    'local11gr2.world',
-                                                    'localhost',
-                                                    '1521')
+    
+    conn = SimpleOracleJDBC::Interface.create('sodonnell',   # user
+                                              'sodonnell',   # password
+                                              'tuned',       # service
+                                              '192.168.0.1', # host
+                                              '1521')        # port
+    
     # ... or create with an existing JDBC connection
-    # @interface = SimpleOracleJDBC.create_with_existing_connection(conn)
-
+    # conn = SimpleOracleJDBC.create_with_existing_connection(conn)
+    
     # Create a SimpleOracleJDBC::SQL object
-    sql = @interface.prepare_sql("select * from dual")
-
-    # execute the query against the database
-    sql.execute
-
-    # get the results back as an array
+    sql = conn.prepare_sql("select 1 c1, 'abc' c2, sysdate c3, 23.56 c4
+                                  from dual
+                                  where 1 = :b1
+                                  and   2 = :b2")
+    
+    # execute the query against the database, passing any binds as required
+    sql.execute(1, 2)
+    
+    # get the results back as an array of arrays. Note that the resultset
+    # and statement will be closed after this call, so the SQL cannot
+    # be executed again.
     results = sql.all_array
-    puts "The returned row is #{results[0][0]}"
-    sql.close
-
-    # ... or a hash
-    # results = sql.execute.all_hash
+    puts "The returned row is #{results[0]}"
+    
+    # > The returned row is [1.0, "abc", 2013-02-12 22:00:23 +0000, 23.56]
+    
+    # Run the same SQL statement again
+    sql = conn.prepare_sql("select 1 c1, 'abc' c2, sysdate c3, 23.56 c4
+                                  from dual
+                                  where 1 = :b1
+                                  and   2 = :b2")
+    
+    sql.execute(1, 2)
+    
+    # This time fetch the results as an array of hashes
+    results = sql.all_hash
+    puts "The returned row is #{results[0]}"
+    puts results[0]["C3"].class
+    
+    # Notice how the column names are the keys of the hash, and the date is converted
+    # into a Ruby Time object.
     #
-    # ... or use a block
-    # sql.execute.each_array do |row|
-    #   process_the_row
-    # end
-
-    # Execute a procedure with an OUT parameter
-    proc = @interface.prepare_proc("begin :return := 'abc'; end;")
+    # > The returned row is {"C1"=>1.0, "C2"=>"abc", "C3"=>2013-02-12 22:03:02 +0000, "C4"=>23.56}
+    # > Time
+    
+    # If you need to iterate over a large result set, then pass a block to the each_array
+    # or each_hash method
+    sql = conn.prepare_sql("select level rnum, 1 c1, 'abc' c2, sysdate c3, 23.56 c4
+                            from dual
+                            where 1 = :b1
+                            and   2 = :b2
+                            connect by level <= 4")
+    
+    sql.execute(1, 2).each_hash do |row|
+      puts row
+    end
+    
+    # > {"RNUM"=>1.0, "C1"=>1.0, "C2"=>"abc", "C3"=>2013-02-12 22:07:14 +0000, "C4"=>23.56}
+    # > {"RNUM"=>2.0, "C1"=>1.0, "C2"=>"abc", "C3"=>2013-02-12 22:07:14 +0000, "C4"=>23.56}
+    # > {"RNUM"=>3.0, "C1"=>1.0, "C2"=>"abc", "C3"=>2013-02-12 22:07:14 +0000, "C4"=>23.56}
+    # > {"RNUM"=>4.0, "C1"=>1.0, "C2"=>"abc", "C3"=>2013-02-12 22:07:14 +0000, "C4"=>23.56}
+    
+    # Finally you can ask for each row one at a time, with each_array or each_hash
+    sql = conn.prepare_sql("select level rnum, 1 c1, 'abc' c2, sysdate c3, 23.56 c4
+                            from dual
+                            where 1 = :b1
+                            and   2 = :b2
+                            connect by level <= 4")
+    sql.execute(1, 2)
+    
+    # If you fetch to the end of the result set, then the statement and
+    # and result set will be closed. Otherwise, call the close method:
+    #
+    # sql.close
+    while row = sql.next_array do
+      puts "The row is #{row}"
+    end
+    
+    # > The row is [1.0, 1.0, "abc", 2013-02-12 22:11:38 +0000, 23.56]
+    # > The row is [2.0, 1.0, "abc", 2013-02-12 22:11:38 +0000, 23.56]
+    # > The row is [3.0, 1.0, "abc", 2013-02-12 22:11:38 +0000, 23.56]
+    # > The row is [4.0, 1.0, "abc", 2013-02-12 22:11:38 +0000, 23.56]
+    
+    
+    # Executing Stored Procedures is easy too, just take care of out and inout parameters.
+    #
+    # create or replace function test_func(i_var integer default null)
+    # return integer
+    # is
+    # begin
+    #   if i_var is not null then
+    #     return i_var;
+    #   else
+    #     return -1;
+    #   end if;
+    # end;
+    # /
+    #
+    # Execute a function with a returned parameter. Notice how the
+    # out/returned parameter is passed as a 3 element array.
+    # The first element defines the Ruby type which is mapped into a SQL type as follows:
+    #
+    #    RUBY_TO_JDBC_TYPES = {
+    #      Date       => OracleTypes::DATE,
+    #      Time       => OracleTypes::TIMESTAMP,
+    #      String     => OracleTypes::VARCHAR,
+    #      Fixnum     => OracleTypes::INTEGER,
+    #      Integer    => OracleTypes::INTEGER,
+    #      Bignum     => OracleTypes::NUMERIC,
+    #      Float      => OracleTypes::NUMERIC,
+    #      :refcursor => OracleTypes::CURSOR
+    #    }
+    #
+    # The second element is the value, which should be nil for out parameters and can take a
+    # value for inout parameters.
+    #
+    # The third parameter should always be :out
+    #
+    # Also notice how the value is retrieved using the [] method, which is indexed from 1 not zero.
+    # In, out and inout parameters can be accessed using the [] method.
+    proc = conn.prepare_proc("begin :return := test_func(); end;")
     proc.execute([String, nil, :out])
     puts "The returned value is #{proc[1]}"
+    
+    # > The returned value is -1
+    
+    # To pass parameters into the function, simply pass plain Ruby values:
+    proc = conn.prepare_proc("begin :return := test_func(:b1); end;")
+    proc.execute([String, nil, :out], 99)
+    puts "The returned value is #{proc[1]}"
+    proc.close
+    
+    # > The returned value is 99
+    
+    # A refcursor is returned from a stored procedure as a SimpleOracleJDBC::SQL object, so it can
+    # be accessed in the way as the SQL examples above:
+    #
+    # create or replace function test_refcursor
+    # return sys_refcursor
+    # is
+    #    v_refc sys_refcursor;
+    # begin
+    #   open v_refc for
+    #   select level rnum, 1 c1, 'abc' c2, sysdate c3, 23.56 c4
+    #   from dual
+    #   connect by level <= 4;
+    #
+    #   return v_refc;
+    # end;
+    # /
+    #
+    proc = conn.prepare_proc("begin :return := test_refcursor; end;")
+    proc.execute([:refcursor, nil, :out])
+    sql_object = proc[1]
+    sql_object.each_hash do |row|
+      puts row
+    end
     proc.close
+    
+    # > {"RNUM"=>1.0, "C1"=>1.0, "C2"=>"abc", "C3"=>2013-02-12 22:32:48 +0000, "C4"=>23.56}
+    # > {"RNUM"=>2.0, "C1"=>1.0, "C2"=>"abc", "C3"=>2013-02-12 22:32:48 +0000, "C4"=>23.56}
+    # > {"RNUM"=>3.0, "C1"=>1.0, "C2"=>"abc", "C3"=>2013-02-12 22:32:48 +0000, "C4"=>23.56}
+    # > {"RNUM"=>4.0, "C1"=>1.0, "C2"=>"abc", "C3"=>2013-02-12 22:32:48 +0000, "C4"=>23.56}
 
-## Datamapping
+
+# Datamapping
 
 Basic Ruby types are mapped automatically into the correct types for JDBC interaction, and the JDBC types are mapped back to Ruby types when they are retrieved from the database.
 
-## TODO (AKA missing features)
+# TODO (AKA missing features)
 
 Bindable types that are not yet supported:
+
  * passing a ref_cursor into a proc
  * binding a CLOB to a procedure
 
 Types that cannot be retrieved from an SQL result set
+
   * CLOB
   * Cursor
   * Long

data/lib/simple_oracle_jdbc/#bindings.rb#

@@ -0,0 +1,214 @@
+module SimpleOracleJDBC
+  module Binding
+
+    # Provides a set of methods to map Ruby types to their JDBC equivalent and back again.
+
+
+    RUBY_TO_JDBC_TYPES = {
+      Date       => OracleTypes::DATE,
+      Time       => OracleTypes::TIMESTAMP,
+      String     => OracleTypes::VARCHAR,
+      Fixnum     => OracleTypes::INTEGER,
+      Integer    => OracleTypes::INTEGER,
+      Bignum     => OracleTypes::NUMERIC,
+      Float      => OracleTypes::NUMERIC,
+      :refcursor => OracleTypes::CURSOR
+    }
+
+    # Given a JDBC prepared call or prepared statement, a value and a bind index, the value
+    # will be bound to JDBC statement.
+    #
+    # If value is a single value, ie not an array in is considered an IN parameter.
+    #
+    # If value is an array, then it should have either 2 or 3 elements.
+    #
+    # * 2 elements indictes the value is an IN parameter, element 0 indicates the type
+    # of the bind variable, and element 1 is the value, eg:
+    #
+    #    [String, "Some_value"]
+    #
+    # * 3 elements indicates the value is an OUT or an IN OUT parameter (useful only when using
+    # stored procedures), eg:
+    #
+    #    [String, "Some_value", :out]
+    #    [:refcursor, nil, :out]
+    #
+    # When binding values, Ruby types are mapped to Java / JDBC types based on the type
+    # of the passed in Ruby object. The mapping is as follows:
+    #
+    #    RUBY_TO_JDBC_TYPES = {
+    #      Date       => OracleTypes::DATE,
+    #      Time       => OracleTypes::TIMESTAMP,
+    #      String     => OracleTypes::VARCHAR,
+    #      Fixnum     => OracleTypes::INTEGER,
+    #      Integer    => OracleTypes::INTEGER,
+    #      Bignum     => OracleTypes::NUMERIC,
+    #      Float      => OracleTypes::NUMERIC,
+    #      :refcursor => OracleTypes::CURSOR
+    #    }
+    #
+    # Note that to bind a ref_cursor, there is no natural Ruby class, so it can only be bound using
+    # the array form for values.
+    #
+    # Also note that in this version, it is not possible to bind a ref_cursor into a procedure - it can
+    # only be retrieved.
+    def bind_value(obj, v, i)
+      type  = v.class
+      value = v
+      if v.is_a? Array
+        # class is being overriden from the input
+        type = v[0]
+        value = v[1]
+
+        if v.length == 3
+          bind_out_parameter(obj, i, type)
+        end
+      end
+
+      if type == Date
+        bind_date(obj, value, i)
+      elsif type == Time
+        bind_time(obj, value, i)
+      elsif type == String
+        bind_string(obj, value, i)
+      elsif type == Fixnum or type == Integer
+        bind_int(obj, value, i)
+      elsif type == Float
+        bind_number(obj, value, i)
+      elsif type == :refcursor
+        bind_refcursor(obj, value, i)
+      else
+        raise UnknownBindType, type.to_s
+      end
+    end
+
+    # Given a open JDBC result set and a column index, the value is retrieved
+    # and mapped into a Ruby type.
+    #
+    # The columns are indexed from 1 in the array.
+    #
+    # If the retrieved value is null, nil is returned.
+    def retrieve_value(obj, i)
+      case obj.get_meta_data.get_column_type_name(i)
+      when 'NUMBER'
+        retrieve_number(obj, i)
+      when 'INTEGER'
+        retrieve_int(obj, i)
+      when 'DATE'
+        retrieve_time(obj, i)
+      when 'TIMESTAMP'
+        retrieve_time(obj, i)
+      when 'CHAR', 'VARCHAR2'
+        retrieve_string(obj, i)
+      else
+        raise UnknownSQLType, obj.get_meta_data.get_column_type_name(i)
+      end
+    end
+
+    # :nodoc:
+    def bind_out_parameter(obj, index, type)
+      internal_type = RUBY_TO_JDBC_TYPES[type] || OracleTypes::VARCHAR
+      obj.register_out_parameter(index, internal_type)
+    end
+
+    def bind_date(obj, v, i)
+      if v
+        # %Q is micro seconds since epoch. Divide by 1000 to get milli-sec
+        jdbc_date = Java::JavaSql::Date.new(v.strftime("%s").to_f * 1000)
+        obj.set_date(i, jdbc_date)
+      else
+        obj.set_null(i, OracleTypes::DATE)
+      end
+    end
+
+    def bind_time(obj, v, i)
+      if v
+        # Need to use an Oracle TIMESTAMP - dates don't allow a time to be specified
+        # for some reason, even though a date in Oracle contains a time.
+        jdbc_time = TIMESTAMP.new(Java::JavaSql::Timestamp.new(v.to_f * 1000))
+        obj.setTIMESTAMP(i, jdbc_time)
+      else
+        obj.set_null(i, OracleTypes::TIMESTAMP)
+      end
+    end
+
+    def bind_string(obj, v, i)
+      if v
+        obj.set_string(i, v)
+      else
+        obj.set_null(i, OracleTypes::VARCHAR)
+      end
+    end
+
+    def bind_int(obj, v, i)
+      if v
+        obj.set_int(i, v)
+      else
+        obj.set_null(i, OracleTypes::INTEGER)
+      end
+    end
+
+    def bind_number(obj, v, i)
+      if v
+        obj.set_number(i, Java::OracleSql::NUMBER.new(v))
+      else
+        obj.set_null(i, OracleTypes::NUMBER)
+      end
+    end
+
+    def bind_refcursor(obj, v, i)
+      if v
+        raise "not implemented"
+      end
+    end
+
+    def retrieve_date(obj, i)
+      jdate = obj.get_date(i)
+      if jdate
+        rt = Time.at(jdate.date_value.get_time.to_f / 1000)
+        Date.new(rt.year, rt.month, rt.day)
+      else
+        nil
+      end
+    end
+
+    def retrieve_time(obj, i)
+      jdate = obj.get_timestamp(i)
+      if jdate
+        Time.at(jdate.get_time.to_f / 1000)
+      else
+        nil
+      end
+    end
+
+    def retrieve_string(obj, i)
+      obj.get_string(i)
+    end
+
+    def retrieve_int(obj, i)
+      v = obj.get_int(i)
+      if obj.was_null
+        nil
+      else
+        v
+      end
+    end
+
+    def retrieve_number(obj, i)
+      v = obj.get_number(i)
+      if v
+        v.double_value
+      else
+        nil
+      end
+    end
+
+    def retrieve_refcursor(obj, i)
+      rset = obj.get_object(i)
+      results = Sql.new
+      results.result_set = rset
+      results
+    end
+
+  end
+end

data/lib/simple_oracle_jdbc/db_call.rb

@@ -16,13 +16,27 @@ module SimpleOracleJDBC
 
     # Takes a JDBC database connection and a procedure call and returns a
     # SimpleOracleJDBC object after preparing the procedure call. The prepared
-    # JDBC callable statement is stored in @call
+    # JDBC callable statement is stored in @call.
+    #
+    # @example Preparing a procedure call
+    #     call = DBCall.prepare(conn, "begin my_proc(:b1, :b2, :b3); end;")
     def self.prepare(conn, sql)
       call = new(conn, sql)
     end
 
     # Takes a JDBC database connection, a procedure call and an optional set of binds and
     # returns a SimpleOracleJDBC object after preparing and executing the procedure call.
+    # Input bind variables can be passed as simple values. If a value must be passed as null
+    # it should be passed in an array with a type:
+    #
+    #     [String, nil]
+    #
+    # TO mark a bind as an out or inout parameter use an array with three elements:
+    #
+    #     [String, nil, :out]
+    #
+    # @example Procedure Call with several binds
+    #    call = DBCall.execute(conn, "begin my_proc(:b1, :b2, :b3); end;", "Input 1 value", [String, nil], [Float, nil, :out])
     def self.execute(conn, sql, *binds)
       call = new(conn,sql)
       call.execute(*binds)
@@ -38,6 +52,10 @@ module SimpleOracleJDBC
     # Executes the prepared callable statement stored in @call.
     #
     # The passed list of bind variables are bound to the object before it is executed.
+    # Seen the class method Execute for a definition of how to bind nulls and in/out parameters
+    #
+    # @example Procedure Call with several binds
+    #    call = DBCall.execute(conn, "begin my_proc(:b1, :b2, :b3); end;", "Input 1 value", [String, nil], [Float, nil, :out])
     def execute(*binds)
       @binds = binds
       @binds.each_with_index do |b,i|
@@ -63,7 +81,7 @@ module SimpleOracleJDBC
     #
     # The bind variables are indexed from 1.
     #
-    # If a refcursor is return, it is retrieved as a SimpleOracleJDBC::Sql object. Other
+    # If a refcursor is returned, it is retrieved as a SimpleOracleJDBC::Sql object. Other
     # values are returned as Ruby classes, such as Date, Time, String, Float etc.
     def [](i)
       if i < 1

data/lib/simple_oracle_jdbc/sql.rb

@@ -67,6 +67,7 @@ module SimpleOracleJDBC
         bind_value(@statement, b, i+1)
       end
 
+      # What about a select that starts with the WITH clause?
       unless @sql =~ /^\s*select/i
         @result_set = nil
         @statement.execute()

metadata

@@ -1,61 +1,80 @@
 --- !ruby/object:Gem::Specification
 name: simpleOracleJDBC
 version: !ruby/object:Gem::Version
-  version: '0.1'
-  prerelease: 
+  prerelease:
+  version: 0.1.1
 platform: ruby
 authors:
 - Stephen O'Donnell
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2013-02-05 00:00:00.000000000 Z
+date: 2013-02-12 00:00:00.000000000 Z
 dependencies: []
-description: A lightweight wrapper around the JDBC interface to make it easier to
-  make SQL and stored procedure calls.
+description: A lightweight wrapper around the JDBC interface to make it easier to make SQL and stored procedure calls.
 email: stephen@betteratoracle.com
 executables: []
 extensions: []
 extra_rdoc_files:
 - README.md
 files:
-- test/binding_test.rb
-- test/db_call_test.rb
-- test/helper.rb
-- test/interface_test.rb
-- test/result_set_test.rb
-- test/sql_test.rb
-- test/test_runner.rb
-- lib/simple_oracle_jdbc/bindings.rb
-- lib/simple_oracle_jdbc/db_call.rb
-- lib/simple_oracle_jdbc/interface.rb
-- lib/simple_oracle_jdbc/result_set.rb
-- lib/simple_oracle_jdbc/sql.rb
-- lib/simple_oracle_jdbc.rb
-- Rakefile.rb
-- README.md
+- !binary |-
+  dGVzdC9iaW5kaW5nX3Rlc3QucmI=
+- !binary |-
+  dGVzdC9kYl9jYWxsX3Rlc3QucmI=
+- !binary |-
+  dGVzdC9oZWxwZXIucmI=
+- !binary |-
+  dGVzdC9pbnRlcmZhY2VfdGVzdC5yYg==
+- !binary |-
+  dGVzdC9yZXN1bHRfc2V0X3Rlc3QucmI=
+- !binary |-
+  dGVzdC9zcWxfdGVzdC5yYg==
+- !binary |-
+  dGVzdC90ZXN0X3J1bm5lci5yYg==
+- !binary |-
+  bGliL3NpbXBsZV9vcmFjbGVfamRiYy5yYg==
+- !binary |-
+  bGliL3NpbXBsZV9vcmFjbGVfamRiYy8jYmluZGluZ3MucmIj
+- !binary |-
+  bGliL3NpbXBsZV9vcmFjbGVfamRiYy9iaW5kaW5ncy5yYg==
+- !binary |-
+  bGliL3NpbXBsZV9vcmFjbGVfamRiYy9kYl9jYWxsLnJi
+- !binary |-
+  bGliL3NpbXBsZV9vcmFjbGVfamRiYy9pbnRlcmZhY2UucmI=
+- !binary |-
+  bGliL3NpbXBsZV9vcmFjbGVfamRiYy9yZXN1bHRfc2V0LnJi
+- !binary |-
+  bGliL3NpbXBsZV9vcmFjbGVfamRiYy9zcWwucmI=
+- !binary |-
+  UmFrZWZpbGUucmI=
+- !binary |-
+  UkVBRE1FLm1k
 homepage: http://betteratoracle.com
 licenses: []
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
-      version: '0'
-required_rubygems_version: !ruby/object:Gem::Requirement
+      version: !binary |-
+        MA==
   none: false
+required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
-      version: '0'
+      version: !binary |-
+        MA==
+  none: false
 requirements: []
-rubyforge_project: 
-rubygems_version: 1.8.24
-signing_key: 
+rubyforge_project:
+rubygems_version: 1.8.25
+signing_key:
 specification_version: 3
 summary: A gem to simplify JDBC database access to Oracle when using JRuby
 test_files: []
+has_rdoc: true