simpleOracleJDBC 0.2.0 → 0.3.0

data/README.md

@@ -190,6 +190,180 @@ The best way to learn how to use Simple Oracle JDBC is to read through the sampl
 
 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.
 
+# PLSQL Arrays
+
+Passing arrays to and from PLSQL objects is somewhat painful. To do this, you need to create type objects on the database, eg:
+
+    create or replace type t_varchar_tab is table of varchar2(100);
+    /
+
+Then you can define PLSQL functions to have input or output parameters of that type, eg:
+
+    create or replace function test_array_varchar(i_array t_varchar2_tab)
+      return t_varchar2_tab
+    is
+      v_return_value t_varchar2_tab;
+    begin
+      v_return_value := t_varchar2_tab();
+      for i in 1..i_array.count loop
+        v_return_value.extend(1);
+        v_return_value(v_return_value.count) := i_array(i);
+      end loop;
+      return v_return_value;
+    end;
+    /
+
+Using the type and function defined above, you can pass an array to the function and receive the result using a similar interface as normal values:
+
+    call = conn.prepare_proc("begin
+                                :out_array := test_array_varchar(:i_array);
+                              end;")
+    call.execute([SimpleOracleJDBC::OraArray, SimpleOracleJDBC::OraArray.new('t_varchar2_tab', nil), :out],
+                 SimpleOracleJDBC::OraArray.new('t_varchar2_tab', ['abc', 'def', nil]))
+    return_array = call[1]
+    return_array.each do |v|
+      puts "The value is: #{v}"
+    end
+
+    # The value is: abc
+    # The value is: def
+    # The value is:
+
+There are a few important differences in the syntax for array calls.
+
+To pass an array in, you must create a SimpleOracleJDBC::OraArray object. This takes 2 parameters:
+
+1. The name of the type on the Oracle database
+2. A Ruby array of values to pass to Oracle.
+
+Right now, an array of Integers, Floats, String, Dates or Times is supported. Nil values are allowed (as shown in the example above).
+
+To receive an array of values, again use the SimpleOracleJDBC::OraArray class. The syntax is similar to receiving any output variable from a stored procedure (ie the 3 element array syntax), except the 2nd element in the array is no longer nil. It is important to create an instance of the OraArray object using the name of the Oracle Type, as this is required to retrieve the results from the PLSQL call.
+
+For in out parameters, simply use the 3 element array syntax as with out parameters, only pass a Ruby array as the second parameter.
+
+The array feature has been tested with Oracle arrays of char, varchar2, integer, number, date, timestamp and raw.
+
+# PLSQL Record Types
+
+Using a similar interface as for PLSQL Arrays, it is possible to bind PLSQL Record types to a stored procedure. A PLSQL record type is define on the database using something like the following:
+
+    create or replace type t_record as object (
+      p_varchar varchar2(10),
+      p_integer integer,
+      p_number  number,
+      p_char    char(10),
+      p_date    date,
+      p_timestamp timestamp,
+      p_raw     raw(10)
+    );
+    /
+    
+    create or replace function test_record(i_record t_record)
+      return t_record
+    is
+    begin
+      return i_record;
+    end;
+    /
+
+Using the type and function above, it is possible to pass a Ruby Array of values for the record and receive a Ruby Array as a response:
+
+    call = conn.prepare_proc("begin
+                               :out_array := test_record(:i_array);
+                              end;")
+    record = ["The String", 123, 456.789, 'THE CHAR', Time.gm(2013,11,23), Time.gm(2013,12,23,12,24,36), 'ED12ED12']
+    call.execute([SimpleOracleJDBC::OraRecord, SimpleOracleJDBC::OraRecord.new('t_record', nil), :out],
+                  SimpleOracleJDBC::OraRecord.new('t_record', record))
+    return_array = call[1]
+    return_array.each do |v|
+      puts "The value is: #{v}"
+    end
+    
+    # The value is: The String
+    # The value is: 123.0
+    # The value is: 456.789
+    # The value is: THE CHAR
+    # The value is: 2013-11-23 00:00:00 +0000
+    # The value is: 2013-12-23 12:24:36 +0000
+    # The value is: ED12ED12
+
+There are a few important differences in the syntax for record calls.
+
+To pass a record in, you must create a SimpleOracleJDBC::OraRecord object. This takes 2 parameters:
+
+1. The name of the type on the Oracle database
+2. A Ruby array of values to pass to Oracle.
+
+The array of Ruby values must contain the same number of fields in the record. To set a field in the record to null pass nil inside the array.
+
+To receive a record from a procedure call, again use the SimpleOracleJDBC::OraRecord class. The syntax is similar to receiving any output variable from a stored procedure (ie the 3 element array syntax), except the 2nd element in the array is no longer nil. It is important to create an instance of the OraRecord object using the name of the Oracle Type, as this is required to retrieve the results from the PLSQL call.
+
+For in out parameters, simply use the 3 element array syntax as with out parameters, only pass a Ruby array as the second parameter.
+
+# Arrays of PLSQL Records
+
+If you define a PLSQL array as table of a record type, then you have an array of PLSQL records. For example, building on the record type created above:
+
+    create or replace type t_record_tab as table of t_record;
+    /
+    
+    create or replace function test_array_of_records(i_array t_record_tab)
+      return t_record_tab
+    is
+      v_return_value t_record_tab;
+    begin
+      v_return_value := t_record_tab();
+      for i in 1..i_array.count loop
+        v_return_value.extend(1);
+        v_return_value(v_return_value.count) := i_array(i);
+      end loop;
+      return v_return_value;
+    end;
+    /
+
+Binding an array like this to a stored procedure works just like binding an array of values. The only difference is that each value passed in the input array, must also be an array. Each of those arrays are then converted into the internal Oracle format using the OraRecord class. For example:
+
+    call = conn.prepare_proc("begin
+                               :out_array := test_array_of_records(:i_array);
+                              end;")
+    record = ["The String", 123, 456.789, 'THE CHAR', Time.gm(2013,11,23), Time.gm(2013,12,23,12,24,36), 'ED12ED12']
+    call.execute([SimpleOracleJDBC::OraArray, SimpleOracleJDBC::OraArray.new('t_record_tab', nil), :out],
+               # ! Note how the record is an array inside of an array
+                  SimpleOracleJDBC::OraArray.new('t_record_tab', [record]))
+    return_array = call[1]
+    return_array.each do |v|
+      # Each return element in the array is an array
+      puts "The value is: #{v[0]}"
+    end
+    
+    # The value is: The String
+
+
+# What About Nested Types?
+
+A nested type is a type that has another type as one of its attributes. Right now they are not supported.
+
+# SQL Arrays
+
+Similar to PLSQL arrays, it is possible to bind an array of values to an SQL call:
+
+        sql = @interface.execute_sql("select * from table(:b_tab)", 
+                                     SimpleOracleJDBC::OraArray.new('t_varchar2_tab', ['abc', 'def']))
+
+Again, instead of passing a simple Ruby type, you need to pass an instance of OraArray as the bind variable.
+
+This also works with PLSQL Arrays of Records, eg:
+
+    sql = @interface.execute_sql("select * from table(:b_tab)",
+                                 SimpleOracleJDBC::OraArray.new('t_record_tab', [
+                                                                  ["S1", nil, nil, nil, nil, nil, nil],
+                                                                  ["S2", nil, nil, nil, nil, nil, nil]                                                                                           ]))
+
+
+More complex types are not yet supported.
+
+
 # TODO (AKA missing features)
 
 Bindable types that are not yet supported:
@@ -199,7 +373,7 @@ Bindable types that are not yet supported:
 
 Types that cannot be retrieved from an SQL result set
 
-  * CLOB
+  * CLOB - is returned as a string so long as it is under 4000 characters
   * Cursor
   * Long
   * nvarchar etc

data/lib/simple_oracle_jdbc.rb

@@ -9,11 +9,19 @@ module SimpleOracleJDBC
   java_import 'oracle.jdbc.OracleTypes'
   java_import 'java.sql.DriverManager'
   java_import 'java.sql.SQLException'
+  java_import 'oracle.sql.ArrayDescriptor'
+  java_import 'oracle.sql.ARRAY'
+  java_import 'oracle.sql.StructDescriptor'
+  java_import 'oracle.sql.STRUCT'
+
 end
 
+require 'simple_oracle_jdbc/type_map'
 require 'simple_oracle_jdbc/bindings'
 require 'simple_oracle_jdbc/result_set'
 #require 'interface'
 require 'simple_oracle_jdbc/sql'
 require 'simple_oracle_jdbc/interface'
 require 'simple_oracle_jdbc/db_call'
+require 'simple_oracle_jdbc/ora_array'
+require 'simple_oracle_jdbc/ora_record'

data/lib/simple_oracle_jdbc/bindings.rb

@@ -1,6 +1,8 @@
 module SimpleOracleJDBC
   module Binding
 
+    include SimpleOracleJDBC::TypeMap
+
     # Provides a set of methods to map Ruby types to their JDBC equivalent and back again.
 
 
@@ -64,7 +66,7 @@ module SimpleOracleJDBC
         value = v[1]
 
         if v.length == 3
-          bind_out_parameter(obj, i, type)
+          bind_out_parameter(obj, i, type, value)
         end
       end
 
@@ -82,6 +84,10 @@ module SimpleOracleJDBC
         bind_refcursor(obj, value, i)
       elsif type == :raw
         bind_raw(obj, value, i)
+      elsif type == SimpleOracleJDBC::OraArray
+        value.bind_to_call(@connection, obj, i)
+      elsif type == SimpleOracleJDBC::OraRecord
+        value.bind_to_call(@connection, obj, i)
       else
         raise UnknownBindType, type.to_s
       end
@@ -113,16 +119,19 @@ module SimpleOracleJDBC
     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)
+    def bind_out_parameter(obj, index, type, value)
+      if type == SimpleOracleJDBC::OraArray or type == SimpleOracleJDBC::OraRecord
+        value.register_as_out_parameter(@connection, obj, index)
+      else
+        internal_type = RUBY_TO_JDBC_TYPES[type] || OracleTypes::VARCHAR
+        obj.register_out_parameter(index, internal_type)
+      end
     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)
+        obj.set_date(i, ruby_date_as_jdbc_date(v))
       else
         obj.set_null(i, OracleTypes::DATE)
       end
@@ -132,8 +141,7 @@ module SimpleOracleJDBC
       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)
+        obj.setTIMESTAMP(i, ruby_time_as_jdbc_timestamp(v))
       else
         obj.set_null(i, OracleTypes::TIMESTAMP)
       end
@@ -157,13 +165,7 @@ module SimpleOracleJDBC
 
     def bind_number(obj, v, i)
       if v
-        # Avoid warning that appeared in JRuby 1.7.3. There are many signatures of
-        # Java::OracleSql::NUMBER and it has to pick one. This causes a warning. This
-        # technique works around the warning and forces it to the the signiture with a
-        # double input - see https://github.com/jruby/jruby/wiki/CallingJavaFromJRuby
-        # under the Constructors section.
-        construct = Java::OracleSql::NUMBER.java_class.constructor(Java::double)
-        obj.set_number(i, construct.new_instance(v))
+        obj.set_number(i, ruby_number_as_jdbc_number(v))
       else
         obj.set_null(i, OracleTypes::NUMBER)
       end
@@ -177,30 +179,20 @@ module SimpleOracleJDBC
 
     def bind_raw(obj, v, i)
       if v
-        raw = Java::OracleSql::RAW.new(v)
-        obj.set_raw(i, raw)
+        obj.set_raw(i, ruby_raw_string_as_jdbc_raw(v))
       else
         obj.set_null(i, OracleTypes::RAW)
       end
     end
 
-
     def retrieve_date(obj, i)
       jdate = obj.get_date(i)
-      if jdate
-        Date.new(jdate.get_year+1900, jdate.get_month+1, jdate.get_date)
-      else
-        nil
-      end
+      java_date_as_date(jdate)
     end
 
     def retrieve_time(obj, i)
       jdate = obj.get_timestamp(i)
-      if jdate
-        Time.at(jdate.get_time.to_f / 1000)
-      else
-        nil
-      end
+      java_date_as_time(jdate)
     end
 
     def retrieve_string(obj, i)
@@ -210,35 +202,27 @@ module SimpleOracleJDBC
     def retrieve_int(obj, i)
       v = obj.get_int(i)
       if obj.was_null
-        nil
-      else
-        v
+        v = nil
       end
+      java_integer_as_integer(v)
     end
 
     def retrieve_number(obj, i)
       v = obj.get_number(i)
-      if v
-        v.double_value
-      else
-        nil
-      end
+      java_number_as_float(v)
     end
 
     def retrieve_refcursor(obj, i)
       rset = obj.get_object(i)
-      results = Sql.new
+      # Dummy connection passed as it is never needed?
+      results = Sql.new(nil)
       results.result_set = rset
       results
     end
 
     def retrieve_raw(obj, i)
       v = obj.get_raw(i)
-      if v
-        v.string_value
-      else
-        nil
-      end
+      oracle_raw_as_string(v)
     end
 
   end

data/lib/simple_oracle_jdbc/db_call.rb

@@ -104,6 +104,8 @@ module SimpleOracleJDBC
           retrieve_refcursor(@call, i)
         elsif bind[0] == :raw
           retrieve_raw(@call, i)
+        elsif bind[0] == SimpleOracleJDBC::OraArray or bind[0] == SimpleOracleJDBC::OraRecord
+          bind[1].retrieve_out_value(@connection, @call, i)
         end
       else
         # If its not an array, it was just an IN, so just pull the bind

data/lib/simple_oracle_jdbc/ora_array.rb

@@ -0,0 +1,133 @@
+module SimpleOracleJDBC
+
+  class OraArray
+    include TypeMap
+
+    attr_reader :ora_type
+
+    # This must be initialized with the name of the Oracle array type as defined
+    # on the database, ie the t_name is table of varchar2(10);
+    #
+    # Values must be an array of Ruby objects, or nil. The values in the array
+    # will be cast into the appropriate Oracle type depending on the definition
+    # of the array defined in Oracle.
+    def initialize(ora_type, values)
+      @ora_type   = ora_type.upcase
+      self.values = values
+      @descriptor = nil
+    end
+
+    # Values must be a Ruby array of objects or nil.
+    #
+    # While the values can be set in upon object initialization, this method
+    # allows them to be changed. The one advantage is that it allows the
+    # array descriptor to be reused across many database calls. As this must
+    # be queried from the database, it requires 1 database round trip for each new object,
+    # but is cached inside the object once it is initialized.
+    def values=(value_array)
+      if value_array and !value_array.is_a? Array
+        raise "The values must be a Ruby array, not #{value_array.class}"
+      end
+      @values = value_array || Array.new
+    end
+
+    # Given a database connection, a prepared statement and a bind index,
+    # this method will bind the array of values (set at object initialization time
+    # or by the values= method) to the statement.
+    def bind_to_call(conn, stmt, index)
+      # First thing that is need is a descriptor for the given type
+      set_descriptor(conn)
+      base_type = @descriptor.get_base_name
+
+      jarray = nil
+      if base_type == 'VARCHAR' or base_type == 'CHAR'
+        jarray = @values.to_java
+      elsif base_type == 'RAW'
+        jarray = @values.map{|i| ruby_raw_string_as_jdbc_raw(i) }.to_java
+      elsif base_type == 'NUMBER' or base_type == 'INTEGER'
+        jarray = @values.map{|i| ruby_number_as_jdbc_number(i) }.to_java
+      elsif base_type == 'DATE' or base_type == 'TIMESTAMP'
+        jarray = @values.map{|i| ruby_any_date_as_jdbc_date(i) }.to_java
+      elsif @values.first.is_a? Array or @values.first.nil?
+        # If the value is an array, assume we are dealing with an array
+        # of records. Also need the nil check as we could be binding
+        # an empty array or a return value.
+        jarray = create_struct_array(conn, base_type,@values)
+      else
+        raise "#{base_type}: Unimplemented Array Type"
+      end
+      ora_array = ARRAY.new(@descriptor, conn, jarray)
+      stmt.set_object(index, ora_array)
+    end
+
+
+    # Given a database connection, a prepared statement and a bind index,
+    # register the bind at that index as an out or inout parameter.
+    def register_as_out_parameter(conn, stmt, index)
+      set_descriptor(conn)
+      stmt.register_out_parameter(index, OracleTypes::ARRAY, @ora_type)
+    end
+
+    # After executing a statement, retrieve the resultant array from Oracle
+    # returning a Ruby array of Ruby objects.
+    def retrieve_out_value(conn, stmt, index)
+      set_descriptor(conn)
+      ora_array = stmt.get_array(index)
+      base_type = ora_array.get_base_type_name
+      if base_type == 'VARCHAR' or base_type == 'CHAR'
+        retrieve_as_string(ora_array)
+      elsif base_type == 'RAW'
+        retrieve_as_raw(ora_array)
+      elsif base_type == 'NUMBER' or base_type == 'INTEGER'
+        retrieve_as_number(ora_array)
+      elsif base_type == 'DATE' or base_type == 'TIMESTAMP'
+        retrieve_as_date(ora_array)
+      else
+        retrieve_oracle_record(conn, base_type, ora_array)
+      end
+    end
+
+    private
+
+    def set_descriptor(conn)
+      @descriptor ||= ArrayDescriptor.createDescriptor(@ora_type, conn);
+    end
+
+    def retrieve_as_string(ora_array)
+      ora_array.get_array.to_a
+    end
+
+    def retrieve_as_number(ora_array)
+      ora_array.get_array.to_a.map{|v| java_number_as_float(v) }
+    end
+
+    def retrieve_as_raw(ora_array)
+      ora_array.get_oracle_array.to_a.map{|v| oracle_raw_as_string(v) }
+    end
+
+    # Always returns dates are Ruby Time objects
+    def retrieve_as_date(ora_array)
+      ora_array.get_array.to_a.map{|v| java_date_as_time(v) }
+    end
+
+    def retrieve_oracle_record(conn, type, ora_array)
+      ora_record = OraRecord.new(type,nil)
+      ora_array.get_array.to_a.map{|r| ora_record.convert_struct_to_ruby(conn, r) }
+    end
+
+    # Converts an array of arrays into their intended Oracle
+    # record type
+    def create_struct_array(conn, type, values)
+      ora_record = OraRecord.new(type, nil)
+      array_of_structs = Array.new
+      values.each do |v|
+        array_of_structs.push ora_record.convert_to_oracle_struct(conn, v)
+      end
+      array_of_structs.to_java
+    end
+
+
+  end
+
+end
+