simpleOracleJDBC 0.1

data/README.md

@@ -0,0 +1,65 @@
+# Simple Oracle JDBC
+
+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.
+
+## 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
+
+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.
+
+    require 'rubygems'
+    require 'simple_oracle_jdbc'
+
+    @interface = SimpleOracleJDBC::Interface.create('sodonnel',
+                                                    'sodonnel',
+                                                    'local11gr2.world',
+                                                    'localhost',
+                                                    '1521')
+    # ... or create with an existing JDBC connection
+    # @interface = 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
+    results = sql.all_array
+    puts "The returned row is #{results[0][0]}"
+    sql.close
+
+    # ... or a hash
+    # results = sql.execute.all_hash
+    #
+    # ... 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;")
+    proc.execute([String, nil, :out])
+    puts "The returned value is #{proc[1]}"
+    proc.close
+
+## 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)
+
+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
+  * nvarchar etc

data/Rakefile.rb

@@ -0,0 +1,30 @@
+desc "Generate RDoc"
+task :doc => ['doc:generate']
+
+namespace :doc do
+  project_root = File.expand_path(File.dirname(__FILE__))
+  doc_destination = File.join(project_root, 'doc')
+
+  begin
+    require 'yard'
+    require 'yard/rake/yardoc_task'
+
+    YARD::Rake::YardocTask.new(:generate) do |yt|
+      yt.files   = Dir.glob(File.join(project_root, 'lib/**/*.rb')) + #, '**', '*.rb')) +
+                   [ File.join(project_root, 'README.md') ]
+      puts yt.files
+      yt.options = ['--output-dir', doc_destination, '--readme', 'README.md']
+    end
+  rescue LoadError
+    desc "Generate YARD Documentation"
+    task :generate do
+      abort "Please install the YARD gem to generate rdoc."
+    end
+  end
+
+  desc "Remove generated documenation"
+  task :clean do
+    rm_r doc_dir if File.exists?(doc_destination)
+  end
+
+end

data/lib/simple_oracle_jdbc.rb

@@ -0,0 +1,19 @@
+require 'java'
+require 'date'
+
+module SimpleOracleJDBC
+  java_import 'oracle.jdbc.OracleDriver'
+  java_import 'oracle.jdbc.OracleConnectionWrapper'
+  java_import 'oracle.sql.TIMESTAMP'
+  java_import 'oracle.sql.NUMBER'
+  java_import 'oracle.jdbc.OracleTypes'
+  java_import 'java.sql.DriverManager'
+  java_import 'java.sql.SQLException'
+end
+
+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'

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

@@ -0,0 +1,105 @@
+module SimpleOracleJDBC
+
+  class DBCall
+
+    # This class is used to prepare and execute stored procedure calls against
+    # the database. The interface is similar to the Sql class.
+    #
+    # @!attribute call
+    #   @return [JDBC Callable Statement] Returns the raw JDBC callable statement
+    #
+
+    include Binding
+
+    attr_reader :call
+
+
+    # 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
+    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.
+    def self.execute(conn, sql, *binds)
+      call = new(conn,sql)
+      call.execute(*binds)
+      call
+    end
+
+    # Similar to the class method prepare.
+    def initialize(conn, sql)
+      @connection = conn
+      @call = @connection.prepare_call(sql)
+    end
+
+    # Executes the prepared callable statement stored in @call.
+    #
+    # The passed list of bind variables are bound to the object before it is executed.
+    def execute(*binds)
+      @binds = binds
+      @binds.each_with_index do |b,i|
+        bind_value(@call, b, i+1)
+      end
+      begin
+        @call.execute
+      rescue Java::JavaSql::SQLException => sqle
+        if sqle.message =~ /no data found/
+          raise SimpleOracleJDBC::NoDataFound, sqle.to_s
+        elsif sqle.message =~ /too many rows/
+          raise SimpleOracleJDBC::TooManyRows, sqle.to_s
+        elsif sqle.message =~ /ORA-2\d+/
+          raise SimpleOracleJDBC::ApplicationError, sqle.to_s
+        else
+          raise
+        end
+      end
+      self
+    end
+
+    # Allows the bound values to be retrieved along with OUT or IN OUT parameters.
+    #
+    # The bind variables are indexed from 1.
+    #
+    # If a refcursor is return, 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
+        raise BindIndexOutOfRange, "Bind indexes must be greater or equal to one"
+      end
+      bind = @binds[i-1]
+      if bind.is_a? Array
+        # If its an array, it means it was in OUT or INOUT parameter
+        if bind[0] == Date
+          retrieve_date(@call, i)
+        elsif bind[0] == Time
+          retrieve_time(@call, i)
+        elsif bind[0] == String
+          retrieve_string(@call, i)
+        elsif bind[0] == Fixnum or bind[0] == Integer
+          retrieve_int(@call, i)
+        elsif bind[0] == Float
+          retrieve_number(@call, i)
+        elsif bind[0] == :refcursor
+          retrieve_refcursor(@call, i)
+        end
+      else
+        # If its not an array, it was just an IN, so just pull the bind
+        # out of the bind array. No need to get it from the DB object.
+        bind
+      end
+    end
+
+    # Closes the callable statement
+    def close
+      if @call
+        @call.close
+        @call = nil
+      end
+      @bind = nil
+    end
+
+  end
+end

data/lib/simple_oracle_jdbc/interface.rb

@@ -0,0 +1,120 @@
+module SimpleOracleJDBC
+
+  class NoDataFound < Exception
+  end
+  class TooManyRows < Exception
+  end
+  class ApplicationError < Exception
+  end
+  class NoResultSet < Exception
+  end
+  class BindIndexOutOfRange < Exception
+  end
+  class UnknownBindType < Exception
+  end
+  class UnknowSQLType < Exception
+  end
+
+  class Interface
+
+    # The Interface class is the intended entry point for the SimpleOracleJDBC gem.
+    #
+    # The SimpleOracleJDBC class  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.
+    #
+    # @!attribute connection
+    #   @return [JDBC Oracle Database connection] Returns the raw JDBC database connection
+
+    attr_accessor :connection
+
+    # Factory method to create a new interface using an existing database connection.
+    # Returns an instance of SimpleOracleJDBC::Interface
+    def self.create_with_existing_connection(conn)
+      connector = self.new
+      connector.set_connection conn
+      connector
+    end
+
+    # Factory method to establish a new JDBC connection and create a new interface.
+    # Returns a SimpleOracleJDBC::Interface
+    def self.create(user, password, database_service, host=nil, port=nil)
+      conn = self.new
+      conn.connect(user, password, database_service, host, port)
+      conn
+    end
+
+    # Establishes a new database connection using the supplied parameters.
+    def connect(user, password, database_service, host=nil, port=nil)
+      oradriver = OracleDriver.new
+
+      DriverManager.registerDriver oradriver
+      @connection = DriverManager.get_connection "jdbc:oracle:thin:@#{host}:#{port}/#{database_service}", user, password
+      @connection.auto_commit = false
+    end
+
+    # Closes the database connection
+    def disconnect
+      if @connection
+        @connection.close
+        @connection = nil
+      end
+    end
+
+    # Performs a commit on the database connection
+    def commit
+      @connection.commit
+    end
+
+    # Performs a rollback on the database connection
+    def rollback
+      @connection.rollback
+    end
+
+    # Prepares a SQL statement using the Sql class.
+    #
+    # Returns a Sql object.
+    def prepare_sql(query)
+      Sql.prepare(@connection, query)
+    end
+
+    # Executes a SQL statement using the Sql class
+    #
+    # Returns a Sql object
+    def execute_sql(query, *binds)
+      Sql.execute(@connection, query, *binds)
+    end
+
+    # Prepares a stored procedure call using the DBCall class.
+    #
+    # Returns a DBCall object
+    def prepare_proc(sql)
+      DBCall.prepare(@connection, sql)
+    end
+
+    alias_method :prepare_call, :prepare_proc
+
+    # Executes a stored procedure call using the DBCall class.
+    #
+    # Returns a DBCall object
+    def execute_proc(sql, *binds)
+      DBCall.execute(@connection, sql, *binds)
+    end
+
+    alias_method :execute_call, :execute_proc
+
+    protected
+
+    def set_connection(conn)
+      @connection = conn
+    end
+
+    private
+
+    def initialize
+    end
+
+  end
+
+end
+