dbd-jdbc 0.0.1

data/README.txt

@@ -0,0 +1,29 @@
+OVERVIEW
+========
+The Jdbc driver for DBI runs only under JRuby, using JRuby's Java integration to act as a thin wrapper around JDBC Connections obtained through DriverManager.  Theoretically this driver can support any database that has JDBC support, although the behavior of certain aspects of the DBI API will differ slightly based on the implementation of the JDBC driver and the underlying database (see LIMITATIONS) 
+
+INSTALLATION
+============
+Besides the ruby files being installed with DBI (in DBD/Jdbc), the JDBC driver classes must be added to the JRuby classpath.  One way to do this on UNIX machines is to place a JDBC driver jarfile in JRUBY_HOME/lib.  Another way is to set the CLASSPATH environment variable.  The jruby (or jruby.bat) script can also be modified to add to the classpath.  In the future there may be more dynamic ways to add jarfiles to the classpath as well; check with the JRuby documentation.
+
+USAGE
+=====
+This driver is used like any standard DBI driver, by requiring 'dbi' and obtaining a connection through the DBI.connect method.  The DSN for the database should be "dbi:" followed by the standard Java database URL (jdbc:<subprotocol>:<subname>).  In addition, the attributes hash passed to the connect method must contain the key/value pair "driver" => <jdbc driver class name>.  For example (MySQL):
+
+dbh = DBI.connect('dbi:jdbc:mysql://localhost:3306/test', 'anonymous', '', { "driver" => "com.mysql.jdbc.Driver" } )
+
+SUPPORTED ATTRIBUTES
+====================
+Besides the mandatory "driver" attribute that must be passed in the DBI connect method, there are additional attributes that can be passed to modify the behavior of the driver.  In addition to setting these attributes during the connect call, they can be set on a driver handle using []= (e.g. dbh["autocommit"] = true).  The currently supported attributes are:
+1) autocommit:  sets the autoCommit status of the underlying JDBC Connection (there is a 1-1 relationship between a DBI Database instance and a JDBC Connection)
+2) nulltype: sets the java.sql.Types constant to use when binding nil to a Statement.  See LIMITATIONS
+
+LIMITATIONS
+===========
+There are limitations to the JDBC driver that are largely based on incompatibilities between the DBI and JDBC APIs, and the differences in underlying JDBC driver implementations.  
+
+1) Binding nil to statements is somewhat unreliable due to the fact that JDBC requires type information in PreparedStatement.setNull(int), but there is no type information associated with nil in ruby.  E.g., statements like DBI.select_all("select * from a, b, c where col1=? and col2=?", "a", nil) might run into problems.  One workaround is to hardcode NULL in the sql statement.  If executing multiple inserts and some values might be nil, the driver will call setNull with the type specified in the driver attribute "nulltype".  If the default fails with a given driver, try specifying different nulltypes such as "dbh['nulltype'] = java.sql.Types::NULL" or "dbh['nulltype'] = java.sql.Types::OTHER" to see if it will work.
+
+2) Type conversion in result sets: Java to Ruby type conversion in results of queries is more limited than in JDBC, since DBI returns an entire row at a time, without type information specified (unlike JDBC ResultSet where getInt, getString, etc allow each column to be typed appropriately).  The driver attempts to convert each data type, relying mostly on getObject() and the JRuby type conversion system.  Due to the fact that JDBC drivers are not constrained to the exact Java types returned for each SQL type, it is possible for some conversion oddities to arise (e.g. returning Java BigDecimal which isn't converted by JRuby, leading to a Java BigDecimal rather than Ruby Fixnum/BigDecimal).
+
+3) Type conversion in prepared statements: In addition to not being able to use type data when returning data, it isn't possible to specify type data directly when binding parameters either (when binding multiple parameters, DBI has ability to set type data, and when calling bind_param, this driver does not currently support type data in the attributes).  Most conversions should work without problem, but there is ambiguity in the Ruby Float type since it can be treated as float or double (or BigDecimal) in Java (and FLOAT, DOUBLE, REAL, NUMERIC, DECIMAL, etc in java.sql.Types).  setDouble() is used to try to retain the highest precision, but some problems have been seen (e.g. Sybase REAL works better with setFloat()).  When doing inserts or retrieval, be sure that the driver keeps the desired precision (the only workaround is to change the database column type to something that works better for doubles with the given JDBC driver and database)

data/Rakefile

@@ -0,0 +1,42 @@
+require 'rake'
+require 'rake/testtask'
+
+task :default => [:test, :package]
+
+desc "Run all tests"
+task :test => [:test_all]
+
+Rake::TestTask.new(:test_all) do |t|
+  t.test_files = FileList['test/**/test_*.rb']
+  t.libs << 'test'
+  t.libs.delete("lib") unless defined?(JRUBY_VERSION)
+end
+
+
+task :filelist do
+  puts FileList['pkg/**/*'].inspect
+end
+
+MANIFEST = FileList["lib/**/*.rb", "test/**/*.rb", "Rakefile", "README.txt"]
+
+file "Manifest.txt" => :manifest
+task :manifest do
+  File.open("Manifest.txt", "w") {|f| MANIFEST.each {|n| f << "#{n}\n"} }
+end
+
+Rake::Task['manifest'].invoke # Always regen manifest, so Hoe has up-to-date list of files
+
+begin
+  require 'hoe'
+  Hoe.new("dbd-jdbc", "0.0.1") do |p|
+    p.rubyforge_name = "jruby-extras"
+    p.url = "http://jruby-extras.rubyforge.org/jruby-ldap"
+    p.author = "Ola Bini"
+    p.email = "ola.bini@gmail.com"
+    p.summary = "JDBC driver for DBI, originally by Kristopher Schmidt"
+  end.spec.dependencies.delete_if { |dep| dep.name == "hoe" }
+rescue LoadError
+  puts "You really need Hoe installed to be able to package this gem"
+rescue => e
+  puts "ignoring error while loading hoe: #{e.to_s}"
+end

data/lib/dbd/Jdbc.rb

@@ -0,0 +1,289 @@
+require 'java'
+require File.dirname(__FILE__) + '/JdbcTypeConversions'
+
+module DBI
+  module DBD
+    module Jdbc
+
+      include_class 'java.sql.Connection'
+
+      VERSION          = "0.0.1"
+
+      def self.driver_name
+        "Jdbc"
+      end
+      
+      class Driver < DBI::BaseDriver
+
+        def initialize
+          super("0.4.0")
+          #attributes specific to this class.  All attributes in the
+          #connect attributes that aren't in this list will be
+          #applied to the database handle
+          @driverAttributes = [ "driver" ]
+        end
+
+        # Stolen from AR-JDBC
+        def driver_class(name)
+          return @driver_class if @driver_class
+
+          driver_class_const = (name[0...1].capitalize + name[1..name.length]).gsub(/\./, '_')
+          driver_class_name = name
+          Driver.module_eval do
+            include_class(driver_class_name) { driver_class_const }
+          end
+          driver_class = Driver.const_get(driver_class_const)
+          raise "You specify a driver for your JDBC connection" unless driver_class
+          @driver_class = driver_class
+        end
+
+        def load(name)
+          java.sql.DriverManager.registerDriver(driver_class(name).new)
+        end
+        
+        def connect(dbname, user, auth, attr)
+          driverClass = attr["driver"]
+          raise InterfaceError.new('driver class name must be specified as "driver" in connection attributes') unless driverClass
+          load(driverClass)
+          connection = java.sql.DriverManager.getConnection("jdbc:"+dbname, user, auth)
+          dbh = Database.new(connection)
+          (attr.keys - @driverAttributes).each { |key| dbh[key] = attr[key] }
+          return dbh
+        rescue NativeException => error
+          raise DBI::DatabaseError.new(error.message)
+        end
+
+      end #Driver
+
+      class Database < DBI::BaseDatabase
+
+        include JdbcTypeConversions
+
+        def initialize(connection)
+          @connection = connection
+          @attributes = {
+            #works with Sybase and Mysql.
+            "nulltype" => java.sql.Types::VARCHAR
+          } 
+        end 
+
+        def disconnect
+          @connection.rollback unless self["autocommit"]
+          @connection.close
+        rescue NativeException => error  
+          raise DBI::DatabaseError.new(error.message)
+        end
+
+        def prepare(sql)
+          return Statement.new(@connection.prepareStatement(sql), self["nulltype"])
+        rescue NativeException => error
+          raise DBI::DatabaseError.new(error.message)
+        end 
+
+        def ping
+          return !@connection.isClosed
+        rescue NativeException => error
+          raise DBI::DatabaseError.new(error.message)
+        end
+
+        def commit
+          @connection.commit()
+        rescue NativeException => error
+          raise DBI::DatabaseError.new(error.message)
+        end
+
+        def rollback
+          @connection.rollback()
+        rescue NativeException => error
+          raise DBI::DatabaseError.new(error.message)
+        end
+
+        def tables
+          rs = @connection.getMetaData.getTables(nil, nil, nil, nil)
+          tables = []
+          while(rs.next())
+            tables << rs.getString(3)
+          end
+          return tables
+        rescue NativeException => error
+          raise DBI::DatabaseError.new(error.message)
+        end
+
+        def columns(table)
+          metaData = @connection.getMetaData()
+          rs = metaData.getColumns(nil, nil, table, nil)
+          columns = []
+          while(rs.next())
+            columns << {
+              "name" => rs.getString(4),
+              "sql_type" => jdbc_to_dbi_sqltype(rs.getShort(5)),
+              "type_name" => rs.getString(6),
+              "precision" => rs.getInt(7),
+              "scale" => rs.getInt(9),
+              "default" => rs.getString(13),
+              "nullable" => (rs.getInt(11) == 1)
+            } 
+          end
+          return columns
+        rescue NativeException => error
+          raise DBI::DatabaseError.new(error.message)
+        end
+
+        def [](attribute)
+          attribute.downcase!
+          check_attribute(attribute)
+          case attribute 
+          when "autocommit" then @connection.getAutoCommit()
+          else 
+            @attributes[attribute]
+          end
+        rescue NativeException => error
+          raise DBI::DatabaseError.new(error.message)
+        end
+
+        def []=(attribute, value)
+          attribute.downcase!
+          check_attribute(attribute)
+          case attribute
+          when "autocommit" then @connection.setAutoCommit(value)
+          else
+            @attributes[attribute] = value
+          end
+        rescue NativeException => error
+          raise DBI::DatabaseError.new(error.message)
+        end
+
+        def __get_java_connection
+          return @connection
+        end
+
+        private
+
+        def check_attribute(attribute)
+          raise DBI::NotSupportedError.new("Database attribute #{attribute} is not supported") unless (attribute == "autocommit" || @attributes.has_key?(attribute))
+        end
+
+      end
+
+      class Statement < DBI::BaseStatement
+
+        include JdbcTypeConversions
+
+        def initialize(statement, nulltype)
+          @statement = statement
+          @nulltype = nulltype
+          @rows = nil
+          @data = [] 
+        end
+
+        def bind_param(param, value, attribs)
+          raise InterfaceError.new("Statement.bind_param only supports numeric placeholder numbers") unless param.is_a?(Fixnum)
+          if value.nil?
+            @statement.setNull(param, @nulltype)
+          elsif value.is_a?(String)
+            @statement.setString(param, value)
+          elsif value.is_a?(Fixnum)
+            #no reason not to coerce it to a long?
+            @statement.setLong(param, value)
+          elsif value.is_a?(Float)
+            #despite DBD spec saying Float->SQL Float, using Double gives
+            #better precision and passes tests that setFloat does not. 
+            @statement.setDouble(param, value)
+          elsif value.is_a?(DBI::Date)
+            @statement.setDate(param, dbidate_to_jdbcdate(value))
+          elsif value.is_a?(DBI::Time)
+            @statement.setTime(param, dbitime_to_jdbctime(value))
+          elsif value.is_a?(DBI::Timestamp)
+            @statement.setTimestamp(param, dbitimestamp_to_jdbctimestamp(value))
+          else
+            @statement.setObject(param, value)
+          end
+        rescue NativeException => error
+          raise DBI::DatabaseError.new(error.message)
+        end  
+
+        def execute
+          if @statement.execute() 
+            @rs = @statement.getResultSet
+            @rows = nil
+            @data.clear
+          else
+            @rs = nil
+            @rows = @statement.getUpdateCount
+          end
+        rescue NativeException => error
+          raise DBI::DatabaseError.new(error.message)
+        end  
+
+        def finish
+          @statement.close()
+          @rs = nil
+          @rows = nil
+        rescue NativeException => error
+          raise DBI::DatabaseError.new(error.message)
+        end  
+
+        def fetch
+          if (@rs && @rs.next())
+            @data.clear
+            metaData = @rs.getMetaData()
+            (1..metaData.getColumnCount()).each do |columnNumber|
+              @data << get_value(columnNumber, @rs, metaData) 
+            end
+            return @data
+          else
+            return nil
+          end
+        rescue NativeException => error
+          raise DBI::DatabaseError.new(error.message)
+        end  
+
+        def column_info
+          info = Array.new
+          return info unless @rs
+          metaData = @rs.getMetaData()
+          (1..metaData.getColumnCount()).each do |columnNumber|
+            info << {
+              "name" => metaData.getColumnName(columnNumber),
+              "sql_type" => jdbc_to_dbi_sqltype(metaData.getColumnType(columnNumber)),
+              "type_name" => metaData.getColumnTypeName(columnNumber),
+              "precision" => metaData.getPrecision(columnNumber),
+              "scale" => metaData.getScale(columnNumber),
+              "nullable" => (metaData.isNullable(columnNumber) == 1)
+            } 
+          end
+          return info
+        rescue NativeException => error
+          raise DBI::DatabaseError.new(error.message)
+        end  
+
+        def rows
+          return @rows
+        end
+
+        private 
+
+        def get_value(columnNumber, rs, metaData)
+          #note only map things that seem unlikely to coerce properly to jruby,
+          #since anything mapped as primitive type cannot be returned as null
+          return case metaData.getColumnType(columnNumber)
+                 when java.sql.Types::BIT
+                   rs.getBoolean(columnNumber)
+                 when java.sql.Types::NUMERIC, java.sql.Types::DECIMAL
+                   metaData.getScale(columnNumber) == 0 ? rs.getLong(columnNumber) : rs.getDouble(columnNumber)
+                 when java.sql.Types::DATE
+                   jdbcdate_to_dbidate(rs.getDate(columnNumber))
+                 when java.sql.Types::TIME
+                   jdbctime_to_dbitime(rs.getTime(columnNumber))
+                 when java.sql.Types::TIMESTAMP
+                   jdbctimestamp_to_dbitimestamp(rs.getTimestamp(columnNumber))
+                 else
+                   rs.getObject(columnNumber)
+                 end
+        end
+
+      end # class Statement
+
+    end # module Jdbc
+  end # module DBD
+end # module DBI

data/lib/dbd/JdbcTypeConversions.rb

@@ -0,0 +1,89 @@
+module JdbcTypeConversions
+
+  include_class 'java.util.Calendar'
+  include_class 'java.sql.Types'
+
+  def jdbc_to_dbi_sqltype(jdbctype)
+    return case jdbctype
+      when Types::BIGINT then DBI::SQL_BIGINT
+      when Types::BINARY then DBI::SQL_BINARY
+      when Types::BIT then DBI::SQL_BIT
+      when Types::CHAR then DBI::SQL_CHAR
+      when Types::DATE then DBI::SQL_DATE
+      when Types::DECIMAL then DBI::SQL_DECIMAL
+      when Types::DOUBLE then DBI::SQL_DOUBLE
+      when Types::FLOAT then DBI::SQL_FLOAT
+      when Types::INTEGER then DBI::SQL_INTEGER
+      when Types::LONGVARBINARY then DBI::SQL_LONGVARBINARY
+      when Types::LONGVARCHAR then DBI::SQL_LONGVARCHAR
+      when Types::NUMERIC then DBI::SQL_NUMERIC
+      when Types::REAL then DBI::SQL_REAL
+      when Types::SMALLINT then DBI::SQL_SMALLINT
+      when Types::TIME then DBI::SQL_TIME
+      when Types::TIMESTAMP then DBI::SQL_TIMESTAMP
+      when Types::TINYINT then DBI::SQL_TINYINT
+      when Types::VARBINARY then DBI::SQL_VARBINARY
+      when Types::VARCHAR then DBI::SQL_VARCHAR
+    else 
+      DBI::SQL_OTHER
+    end
+  end
+
+  def dbidate_to_jdbcdate(dbidate)
+    cal = Calendar.getInstance()
+    set_calendar_date_fields(dbidate, cal)
+    return java.sql.Date.new(cal.getTime().getTime())
+  end 
+
+  def dbitime_to_jdbctime(dbitime)
+    cal = Calendar.getInstance()
+    set_calendar_time_fields(dbitime, cal)
+    return java.sql.Time.new(cal.getTime().getTime())
+  end 
+
+  def dbitimestamp_to_jdbctimestamp(dbitimestamp)
+    cal = Calendar.getInstance()
+    set_calendar_date_fields(dbitimestamp, cal)
+    set_calendar_time_fields(dbitimestamp, cal)
+    return java.sql.Timestamp.new(cal.getTime().getTime())
+  end
+
+  def jdbcdate_to_dbidate(jdbcdate)
+    return nil if jdbcdate.nil?
+    cal = get_calendar(jdbcdate)
+    return DBI::Date.new(cal.get(Calendar::YEAR), cal.get(Calendar::MONTH)+1, cal.get(Calendar::DAY_OF_MONTH))
+  end
+
+  def jdbctime_to_dbitime(jdbctime)
+    return nil if jdbctime.nil?
+    cal = get_calendar(jdbctime) 
+    return DBI::Time.new(cal.get(Calendar::HOUR_OF_DAY), cal.get(Calendar::MINUTE), cal.get(Calendar::SECOND))
+  end
+
+  def jdbctimestamp_to_dbitimestamp(jdbctimestamp)
+    return nil if jdbctimestamp.nil?
+    cal = get_calendar(jdbctimestamp)
+    return DBI::Timestamp.new(cal.get(Calendar::YEAR), cal.get(Calendar::MONTH)+1, cal.get(Calendar::DAY_OF_MONTH), cal.get(Calendar::HOUR_OF_DAY), cal.get(Calendar::MINUTE), cal.get(Calendar::SECOND))
+  end
+
+  private
+
+  def set_calendar_date_fields(dbidate, cal)
+    cal.set(Calendar::YEAR, dbidate.year)
+    cal.set(Calendar::MONTH, dbidate.month-1)
+    cal.set(Calendar::DAY_OF_MONTH, dbidate.day)
+  end
+
+  def set_calendar_time_fields(dbitime, cal)
+    cal.set(Calendar::HOUR_OF_DAY, dbitime.hour)
+    cal.set(Calendar::MINUTE, dbitime.minute)
+    cal.set(Calendar::SECOND, dbitime.second) 
+  end
+
+  def get_calendar(jdbctype)
+    cal = Calendar.getInstance()
+    cal.setTime(java.util.Date.new(jdbctype.getTime()))
+    return cal
+  end
+
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification 
+extensions: []
+
+homepage: http://jruby-extras.rubyforge.org/jruby-ldap
+executables: []
+
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+post_install_message: 
+date: 2008-10-08 22:00:00 +00:00
+files: 
+- lib/dbd/Jdbc.rb
+- lib/dbd/JdbcTypeConversions.rb
+- Rakefile
+- README.txt
+rubygems_version: 1.2.0
+rdoc_options: 
+- --main
+- README.txt
+signing_key: 
+cert_chain: []
+
+name: dbd-jdbc
+has_rdoc: true
+platform: ruby
+summary: JDBC driver for DBI, originally by Kristopher Schmidt
+default_executable: 
+bindir: bin
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  version: 
+  requirements: 
+  - - '>='
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_ruby_version: !ruby/object:Gem::Requirement 
+  version: 
+  requirements: 
+  - - '>='
+    - !ruby/object:Gem::Version 
+      version: "0"
+require_paths: 
+- lib
+specification_version: 2
+test_files: []
+
+dependencies: []
+
+description: ""
+email: ola.bini@gmail.com
+authors: 
+- Ola Bini
+extra_rdoc_files: 
+- README.txt
+requirements: []
+
+rubyforge_project: jruby-extras
+autorequire: