activerecord-jdbc-adapter 1.3.0.beta2 → 1.3.0.rc1

data/lib/arjdbc/hsqldb/adapter.rb

@@ -4,13 +4,15 @@ require 'arjdbc/hsqldb/explain_support'
 module ArJdbc
   module HSQLDB
     include ExplainSupport
-    
+
+    # @see ActiveRecord::ConnectionAdapters::JdbcColumn#column_types
     def self.column_selector
-      [ /hsqldb/i, lambda { |cfg, column| column.extend(::ArJdbc::HSQLDB::Column) } ]
+      [ /hsqldb/i, lambda { |config, column| column.extend(Column) } ]
     end
 
+    # @see ActiveRecord::ConnectionAdapters::JdbcColumn
     module Column
-      
+
       private
 
       def extract_limit(sql_type)
@@ -21,7 +23,7 @@ module ArJdbc
         when /^bigint/i      then @sql_type = 'bigint'; limit = 8
         when /^double/i      then @sql_type = 'double'; limit = 8
         when /^real/i        then @sql_type = 'real'; limit = 8
-        # NOTE: once again we get incorrect "limits" from HypesSQL's JDBC 
+        # NOTE: once again we get incorrect "limits" from HypesSQL's JDBC
         # thus yet again we need to fix incorrectly detected limits :
         when /^integer/i     then @sql_type = 'integer'; limit = 4
         when /^float/i       then @sql_type = 'float';   limit = 8
@@ -31,79 +33,82 @@ module ArJdbc
         when /^time/i        then @sql_type = 'time'; limit = nil
         when /^date/i        then @sql_type = 'date'; limit = nil
         else
-          # HSQLDB appears to return "LONGVARCHAR(0)" for :text columns, 
+          # HSQLDB appears to return "LONGVARCHAR(0)" for :text columns,
           # which for AR purposes should be interpreted as "no limit" :
           limit = nil if sql_type =~ /\(0\)$/
         end
         limit
       end
-      
+
       def simplified_type(field_type)
         case field_type
-        when /longvarchar/i then :text
-        when /int/i         then :integer # TINYINT, SMALLINT, BIGINT, INT
-        when /real|double/i then :float
-        when /bit/i         then :boolean
-        when /binary/i      then :binary # VARBINARY, LONGVARBINARY
+        when /^nvarchar/i    then :string
+        when /^character/i   then :string
+        when /^longvarchar/i then :text
+        when /int/i          then :integer # TINYINT, SMALLINT, BIGINT, INT
+        when /real|double/i  then :float
+        when /^bit/i         then :boolean
+        when /binary/i       then :binary # VARBINARY, LONGVARBINARY
         else
           super
         end
       end
-      
+
       # Post process default value from JDBC into a Rails-friendly format (columns{-internal})
       def default_value(value)
         # JDBC returns column default strings with actual single quotes around the value.
         return $1 if value =~ /^'(.*)'$/
         value
       end
-      
+
     end
 
-    ADAPTER_NAME = 'HSQLDB' # :nodoc:
-    
-    def adapter_name # :nodoc:
-      ADAPTER_NAME
+    # @see ActiveRecord::ConnectionAdapters::Jdbc::ArelSupport
+    def self.arel_visitor_type(config = nil)
+      require 'arel/visitors/hsqldb'; ::Arel::Visitors::HSQLDB
     end
 
-    def self.arel2_visitors(config)
-      require 'arel/visitors/hsqldb'
-      {
-        'hsqldb' => ::Arel::Visitors::HSQLDB,
-        'jdbchsqldb' => ::Arel::Visitors::HSQLDB,
-      }
+    ADAPTER_NAME = 'HSQLDB'.freeze
+
+    def adapter_name
+      ADAPTER_NAME
     end
-    
+
     NATIVE_DATABASE_TYPES = {
       :primary_key => "integer GENERATED BY DEFAULT AS IDENTITY(START WITH 0) PRIMARY KEY",
-      :string => { :name => "varchar", :limit => 255 },
+      :string => { :name => "varchar", :limit => 255 }, # :limit => 2147483647
       :text => { :name => "clob" },
       :binary => { :name => "blob" },
-      :boolean => { :name => "boolean" },
+      :boolean => { :name => "boolean" }, # :name => "tinyint", :limit => 1
+      :bit => { :name=>"bit" }, # stored as 0/1 on HSQLDB 2.2 (translates true/false)
       :integer => { :name => "integer", :limit => 4 },
-      :float => { :name => "float", :limit => 8 },
+      :decimal => { :name => "decimal" }, # :limit => 2147483647
+      :numeric => { :name => "numeric" }, # :limit => 2147483647
       # NOTE: fix incorrectly detected limits :
       :tinyint => { :name => "tinyint", :limit => 1 },
       :smallint => { :name => "smallint", :limit => 2 },
       :bigint => { :name => "bigint", :limit => 8 },
+      :float => { :name => "float" },
       :double => { :name => "double", :limit => 8 },
       :real => { :name => "real", :limit => 8 },
+      :date => { :name=>"date" },
+      :time => { :name=>"time" },
+      :timestamp => { :name=>"timestamp" },
+      :datetime => { :name=>"timestamp" },
+      :other => { :name=>"other" },
+      # NOTE: would be great if AR allowed as to refactor as :
+      #   t.column :string, :ignorecase => true
+      :character => { :name => "character" },
+      :varchar_ignorecase => { :name => "varchar_ignorecase" },
     }
-    
+
+    # @override
     def native_database_types
-      super.merge NATIVE_DATABASE_TYPES
-    end
-    
-    def modify_types(types)
-      super(types)
-      types[:primary_key] = NATIVE_DATABASE_TYPES[:primary_key]
-      types[:string] = NATIVE_DATABASE_TYPES[:string].dup
-      #types[:integer][:limit] = nil
-      #types[:boolean][:limit] = nil
-      types[:text][:limit] = nil
-      types
+      NATIVE_DATABASE_TYPES
     end
 
-    def quote(value, column = nil) # :nodoc:
+    # @override
+    def quote(value, column = nil)
       return value.quoted_id if value.respond_to?(:quoted_id)
 
       case value
@@ -118,8 +123,12 @@ module ArJdbc
           "'#{quote_string(value)}'"
         end
       when Time
-        if column && column.type == :time
+        column_type = column && column.type
+        if column_type == :time
           "'#{value.strftime("%H:%M:%S")}'"
+        #elsif column_type == :timestamp # || column_type == :datetime
+          #value = ::ActiveRecord::Base.default_timezone == :utc ? value.getutc : value.getlocal
+          #"'#{value.strftime("%Y-%m-%d %H:%M:%S")}.#{sprintf("%06d", value.usec)}'"
         else
           super
         end
@@ -128,7 +137,21 @@ module ArJdbc
       end
     end
 
-    def quote_column_name(name) # :nodoc:
+    # Quote date/time values for use in SQL input.
+    # Includes microseconds if the value is a Time responding to usec.
+    # @override
+    def quoted_date(value)
+      if value.acts_like?(:time) && value.respond_to?(:usec)
+        usec = sprintf("%06d", value.usec)
+        value = ::ActiveRecord::Base.default_timezone == :utc ? value.getutc : value.getlocal
+        "#{value.strftime("%Y-%m-%d %H:%M:%S")}.#{usec}"
+      else
+        super
+      end
+    end if ::ActiveRecord::VERSION::MAJOR >= 3
+
+    # @override
+    def quote_column_name(name)
       name = name.to_s
       if name =~ /[-]/
         %Q{"#{name.upcase}"}
@@ -137,13 +160,15 @@ module ArJdbc
       end
     end
 
+    # @override
     def add_column(table_name, column_name, type, options = {})
       add_column_sql = "ALTER TABLE #{quote_table_name(table_name)} ADD #{quote_column_name(column_name)} #{type_to_sql(type, options[:limit], options[:precision], options[:scale])}"
       add_column_options!(add_column_sql, options)
       execute(add_column_sql)
     end
 
-    def change_column(table_name, column_name, type, options = {}) #:nodoc:
+    # @override
+    def change_column(table_name, column_name, type, options = {})
       execute "ALTER TABLE #{table_name} ALTER COLUMN #{column_name} #{type_to_sql(type, options[:limit])}"
     end
 
@@ -151,17 +176,18 @@ module ArJdbc
       execute "ALTER TABLE #{table_name} ALTER COLUMN #{column_name} SET DEFAULT #{quote(default)}"
     end
 
+    # @override
     def rename_column(table_name, column_name, new_column_name) #:nodoc:
       execute "ALTER TABLE #{table_name} ALTER COLUMN #{column_name} RENAME TO #{new_column_name}"
     end
 
-    # Maps logical Rails types to MySQL-specific data types.
+    # @override
     def type_to_sql(type, limit = nil, precision = nil, scale = nil)
       return super if defined?(::Jdbc::H2) || type.to_s != 'integer' || limit == nil
-
       type
     end
 
+    # @override
     def rename_table(name, new_name)
       execute "ALTER TABLE #{name} RENAME TO #{new_name}"
     end
@@ -171,46 +197,47 @@ module ArJdbc
       Integer(identity.nil? ? 0 : identity)
     end
 
+    # @private
     def _execute(sql, name = nil)
       result = super
       self.class.insert?(sql) ? last_insert_id : result
     end
     private :_execute
 
-    def add_limit_offset!(sql, options) #:nodoc:
+    # @note Only used with (non-AREL) ActiveRecord **2.3**.
+    # @see Arel::Visitors::HSQLDB#limit_offset
+    def add_limit_offset!(sql, options)
       if sql =~ /^select/i
         offset = options[:offset] || 0
-        bef = sql[7..-1]
         if limit = options[:limit]
-          sql.replace "SELECT LIMIT #{offset} #{limit} #{bef}"
+          sql.replace "SELECT LIMIT #{offset} #{limit} #{sql[7..-1]}"
         elsif offset > 0
-          sql.replace "SELECT LIMIT #{offset} 0 #{bef}"
+          sql.replace "SELECT LIMIT #{offset} 0 #{sql[7..-1]}"
         end
       end
-    end
+    end if ::ActiveRecord::VERSION::MAJOR < 3
 
+    # @override
     def empty_insert_statement_value
-      # on HSQLDB only work with tables that have a default value for each 
+      # on HSQLDB only work with tables that have a default value for each
       # and every column ... you'll need to avoid `Model.create!` on 4.0
       'DEFAULT VALUES'
     end
-    
-    # filter out system tables (that otherwise end up in db/schema.rb)
-    # JdbcConnection#tables
-    # now takes an optional block filter so we can screen out
-    # rows corresponding to system tables.  HSQLDB names its
-    # system tables SYSTEM.*, but H2 seems to name them without
-    # any kind of convention
+
+    # We filter out HSQLDB's system tables (named "SYSTEM.*").
+    # @override
     def tables
       @connection.tables.select { |row| row.to_s !~ /^system_/i }
     end
 
+    # @override
     def remove_index(table_name, options = {})
       execute "DROP INDEX #{quote_column_name(index_name(table_name, options))}"
     end
-    
+
+    # @override
     def structure_dump
-      execute('SCRIPT').map do |result| 
+      execute('SCRIPT').map do |result|
         # [ { 'command' => SQL }, { 'command' ... }, ... ]
         case sql = result.first[1] # ['command']
         when /CREATE USER SA PASSWORD DIGEST .*?/i then nil
@@ -221,24 +248,28 @@ module ArJdbc
       end.compact.join("\n\n")
     end
 
+    # @see #structure_dump
     def structure_load(dump)
       dump.each_line("\n\n") { |ddl| execute(ddl) }
     end
-    
+
     def shutdown
       execute 'SHUTDOWN'
     end
-    
-    def recreate_database(name = nil, options = {}) # :nodoc:
+
+    # @private
+    def recreate_database(name = nil, options = {})
       drop_database(name)
       create_database(name, options)
     end
-    
-    def create_database(name = nil, options = {}); end # :nodoc:
-    
-    def drop_database(name = nil) # :nodoc:
+
+    # @private
+    def create_database(name = nil, options = {}); end
+
+    # @private
+    def drop_database(name = nil)
       execute('DROP SCHEMA PUBLIC CASCADE')
     end
-    
+
   end
 end

data/lib/arjdbc/jdbc/adapter.rb

@@ -8,59 +8,99 @@ require 'arjdbc/jdbc/connection_methods'
 require 'arjdbc/jdbc/driver'
 require 'arjdbc/jdbc/column'
 require 'arjdbc/jdbc/connection'
+require 'arjdbc/jdbc/arel_support'
 require 'arjdbc/jdbc/callbacks'
 require 'arjdbc/jdbc/extension'
 require 'arjdbc/jdbc/type_converter'
 
 module ActiveRecord
   module ConnectionAdapters
+    # Built on top of `ActiveRecord::ConnectionAdapters::AbstractAdapter` which
+    # provides the abstract interface for database-specific functionality, this
+    # class serves 2 purposes in AR-JDBC :
+    # - as a base class for sub-classes
+    # - usable standalone (or with a mixed in adapter spec module)
+    #
+    # Historically this class is mostly been used standalone and that's still a
+    # valid use-case esp. since (with it's `arjdbc.jdbc.RubyJdbcConnectionClass`)
+    # JDBC provides a unified interface for all databases in Java it tries to do
+    # it's best implementing all `ActiveRecord` functionality on top of that.
+    # This might no be perfect that's why it checks for a `config[:adapter_spec]`
+    # module (or tries to resolve one from the JDBC driver's meta-data) and if
+    # the database has "extended" AR-JDBC support mixes in the given module for
+    # each adapter instance.
+    # This is sufficient for most database specific specs we support, but for
+    # compatibility with native (MRI) adapters it's perfectly fine to sub-class
+    # the adapter and override some of its API methods.
     class JdbcAdapter < AbstractAdapter
       extend ShadowCoreMethods
-      
-      include JdbcConnectionPoolCallbacks
-      
+
+      include Jdbc::ArelSupport
+      include Jdbc::ConnectionPoolCallbacks
+
       attr_reader :config
-      
-      def initialize(connection, logger, config = nil) # (logger, config)
-        if config.nil? && logger.respond_to?(:key?) # only 2 arguments given
+
+      # Initializes the (JDBC connection) adapter instance.
+      # The passed configuration Hash's keys are symbolized, thus changes to
+      # the original `config` keys won't be reflected in the adapter.
+      # If the adapter's sub-class or the spec module that this instance will
+      # extend in responds to `configure_connection` than it will be called.
+      # @param connection an (optional) connection instance
+      # @param logger the `ActiveRecord::Base.logger` to use (or nil)
+      # @param config the database configuration
+      # @note `initialize(logger, config)` with 2 arguments is supported as well
+      def initialize(connection, logger, config = nil)
+        if config.nil? && logger.respond_to?(:key?) # (logger, config)
           config, logger, connection = logger, connection, nil
         end
-        
-        @config = config
-        
+
+        @config = config.respond_to?(:symbolize_keys) ? config.symbolize_keys : config
+        # NOTE: JDBC 4.0 drivers support checking if connection isValid
+        # thus no need to @config[:connection_alive_sql] ||= 'SELECT 1'
+        #
+        # NOTE: setup to retry 5-times previously - maybe do not set at all ?
+        @config[:retry_count] ||= 1
+
         @config[:adapter_spec] = adapter_spec(@config) unless @config.key?(:adapter_spec)
         spec = @config[:adapter_spec]
-        
-        connection ||= jdbc_connection_class(spec).new(@config)
-        
-        super(connection, logger)
-        
+
         # kind of like `extend ArJdbc::MyDB if self.class == JdbcAdapter` :
         klass = @config[:adapter_class]
         extend spec if spec && ( ! klass || klass == JdbcAdapter)
-        
-        connection.adapter = self # prepares native database types
-        
+        # NOTE: adapter spec's init_connection only called if instantiated here :
+        connection ||= jdbc_connection_class(spec).new(@config, self)
+
+        super(connection, logger)
+
         # NOTE: should not be necessary for JNDI due reconnect! on checkout :
         configure_connection if respond_to?(:configure_connection)
-        
-        JndiConnectionPoolCallbacks.prepare(self, connection)
-        
-        @visitor = new_visitor(@config) # nil if no AREL (AR-2.3)
+
+        Jdbc::JndiConnectionPoolCallbacks.prepare(self, connection)
+
+        @visitor = new_visitor # nil if no AREL (AR-2.3)
       end
-      
+
+      # Returns the (JDBC) connection class to be used for this adapter.
+      # This is used by (database specific) spec modules to override the class
+      # used assuming some of the available methods have been re-defined.
+      # @see ActiveRecord::ConnectionAdapters::JdbcConnection
       def jdbc_connection_class(spec)
         connection_class = spec.jdbc_connection_class if spec && spec.respond_to?(:jdbc_connection_class)
         connection_class ? connection_class : ::ActiveRecord::ConnectionAdapters::JdbcConnection
       end
 
+      # Returns the (JDBC) `ActiveRecord` column class for this adapter.
+      # This is used by (database specific) spec modules to override the class.
+      # @see ActiveRecord::ConnectionAdapters::JdbcColumn
       def jdbc_column_class
-        ActiveRecord::ConnectionAdapters::JdbcColumn
+        ::ActiveRecord::ConnectionAdapters::JdbcColumn
       end
 
-      # Retrieve the raw java.sql.Connection object.
-      # The unwrap parameter is useful if an attempt to unwrap a pooled (JNDI) 
-      # connection should be made - to really return the native (SQL) object.
+      # Retrieve the raw `java.sql.Connection` object.
+      # The unwrap parameter is useful if an attempt to unwrap a pooled (JNDI)
+      # connection should be made - to really return the 'native' JDBC object.
+      # @param unwrap [true, false] whether to unwrap the connection object
+      # @return [Java::JavaSql::Connection] the JDBC connection
       def jdbc_connection(unwrap = nil)
         java_connection = raw_connection.connection
         return java_connection unless unwrap
@@ -75,7 +115,14 @@ module ActiveRecord
         end
       end
 
-      # Locate specialized adapter specification if one exists based on config data
+      # Locate the specialized (database specific) adapter specification module
+      # if one exists based on provided configuration data. This module will than
+      # extend an instance of the adapter (unless an `:adapter_class` provided).
+      #
+      # This method is called during {#initialize} unless an explicit
+      # `config[:adapter_spec]` is set.
+      # @param config the configuration to check for `:adapter_spec`
+      # @return [Module] the database specific module
       def adapter_spec(config)
         dialect = (config[:dialect] || config[:driver]).to_s
         ::ArJdbc.modules.each do |constant| # e.g. ArJdbc::MySQL
@@ -87,7 +134,7 @@ module ActiveRecord
 
         if (config[:jndi] || config[:data_source]) && ! config[:dialect]
           begin
-            data_source = config[:data_source] || 
+            data_source = config[:data_source] ||
               Java::JavaxNaming::InitialContext.new.lookup(config[:jndi])
             connection = data_source.getConnection
             config[:dialect] = connection.getMetaData.getDatabaseProductName
@@ -103,33 +150,40 @@ module ActiveRecord
         nil
       end
 
-      def modify_types(types)
-        types
+      ADAPTER_NAME = 'JDBC'.freeze
+
+      # @return [String] the 'JDBC' adapter name.
+      def adapter_name
+        ADAPTER_NAME
       end
 
-      def adapter_name # :nodoc:
-        'JDBC'
+      # @override
+      # Will return true even when native adapter classes passed in
+      # e.g. `jdbc_adapter.is_a? ConnectionAdapter::PostgresqlAdapter`
+      #
+      # This is only necessary (for built-in adapters) when
+      # `config[:adapter_class]` is forced to `nil` and the `:adapter_spec`
+      # module is used to extend the `JdbcAdapter`, otherwise we replace the
+      # class constants for built-in adapters (MySQL, PostgreSQL and SQLite3).
+      def is_a?(klass)
+        # This is to fake out current_adapter? conditional logic in AR tests
+        if klass.is_a?(Class) && klass.name =~ /#{adapter_name}Adapter$/i
+          true
+        else
+          super
+        end
       end
 
+      # @deprecated re-implemented - no longer used
+      # @return [Hash] the AREL visitor to use
+      # If there's a `self.arel2_visitors(config)` method on the adapter
+      # spec than it is preferred and will be used instead of this one.
       def self.arel2_visitors(config)
         { 'jdbc' => ::Arel::Visitors::ToSql }
       end
 
-      # NOTE: called from {ConnectionPool#checkout} (up till AR-3.2)
-      def self.visitor_for(pool)
-        config = pool.spec.config
-        adapter = config[:adapter] # e.g. "sqlite3" (based on {#adapter_name})
-        unless visitor = ::Arel::Visitors::VISITORS[ adapter ]
-          adapter_spec = config[:adapter_spec] || self # e.g. ArJdbc::SQLite3
-          if adapter =~ /^(jdbc|jndi)$/
-            visitor = adapter_spec.arel2_visitors(config).values.first
-          else
-            visitor = adapter_spec.arel2_visitors(config)[adapter]
-          end
-        end
-        ( prepared_statements?(config) ? visitor : bind_substitution(visitor) ).new(pool)
-      end
-
+      # @deprecated re-implemented - no longer used
+      # @see #arel2_visitors
       def self.configure_arel2_visitors(config)
         visitors = ::Arel::Visitors::VISITORS
         klass = config[:adapter_spec]
@@ -144,83 +198,45 @@ module ActiveRecord
         visitor
       end
 
-      def new_visitor(config = self.config)
-        visitor = ::Arel::Visitors::VISITORS[ adapter = config[:adapter] ]
-        unless visitor
-          visitor = self.class.configure_arel2_visitors(config)
-          unless visitor
-            raise "no visitor configured for adapter: #{adapter.inspect}"
-          end
-        end
-        ( prepared_statements? ? visitor : bind_substitution(visitor) ).new(self)
-      end
-      protected :new_visitor
-      
-      unless defined? ::Arel::Visitors::VISITORS # NO-OP when no AREL (AR-2.3)
-        def self.configure_arel2_visitors(config); end
-        def new_visitor(config = self.config); end
-      end
-      
-      @@bind_substitutions = nil
-      
-      # @return a {#Arel::Visitors::BindVisitor} class for given visitor type
-      def self.bind_substitution(visitor)
-        # NOTE: similar convention as in AR (but no base substitution type) :
-        # class BindSubstitution < ::Arel::Visitors::ToSql
-        #   include ::Arel::Visitors::BindVisitor
-        # end
-        return const_get(:BindSubstitution) if const_defined?(:BindSubstitution)
-        
-        @@bind_substitutions ||= Java::JavaUtil::HashMap.new
-        unless bind_visitor = @@bind_substitutions.get(visitor)
-          @@bind_substitutions.synchronized do
-            unless @@bind_substitutions.get(visitor)
-              bind_visitor = Class.new(visitor) do
-                include ::Arel::Visitors::BindVisitor
-              end
-              @@bind_substitutions.put(visitor, bind_visitor)
-            end
-          end
-          bind_visitor = @@bind_substitutions.get(visitor)
+      # DB specific types are detected but adapter specs (or extenders) are
+      # expected to hand tune these types for concrete databases.
+      # @return [Hash] the native database types
+      # @override
+      def native_database_types
+        @native_database_types ||= begin
+          types = @connection.native_database_types
+          modify_types(types)
+          types
         end
-        bind_visitor
-      end
-      
-      begin 
-        require 'arel/visitors/bind_visitor'
-      rescue LoadError # AR-3.0
-        def self.bind_substitution(visitor); visitor; end
-      end
-      
-      def bind_substitution(visitor); self.class.bind_substitution(visitor); end
-      private :bind_substitution
-      
-      # @override default implementation (does nothing silently)
+      end
+
+      # Allows for modification of the detected native types.
+      # @param types the resolved native database types
+      # @see #native_database_types
+      def modify_types(types)
+        types
+      end
+
+      # Abstract adapter default implementation does nothing silently.
+      # @override
       def structure_dump
         raise NotImplementedError, "structure_dump not supported"
       end
-      
-      def is_a?(klass) # :nodoc:
-        # This is to fake out current_adapter? conditional logic in AR tests
-        if Class === klass && klass.name =~ /#{adapter_name}Adapter$/i
-          true
-        else
-          super
-        end
-      end
 
+      # JDBC adapters support migration.
+      # @return [true]
+      # @override
       def supports_migrations?
         true
       end
 
-      def native_database_types # :nodoc:
-        @connection.native_database_types
-      end
-
-      def database_name # :nodoc:
+      # Returns the underlying database name.
+      # @override
+      def database_name
         @connection.database_name
       end
 
+      # @private
       def native_sql_to_type(type)
         if /^(.*?)\(([0-9]+)\)/ =~ type
           tname, limit = $1, $2.to_i
@@ -232,7 +248,7 @@ module ActiveRecord
               if name == :primary_key
                 next
               end
-              if val[:name].downcase == tname.downcase && 
+              if val[:name].downcase == tname.downcase &&
                   ( val[:limit].nil? || val[:limit].to_i == limit )
                 return name, limit
               end
@@ -256,47 +272,147 @@ module ActiveRecord
         return nil, nil
       end
 
+      # @override
       def active?
         @connection.active?
       end
 
+      # @override
       def reconnect!
         @connection.reconnect! # handles adapter.configure_connection
         @connection
       end
 
+      # @override
       def disconnect!
         @connection.disconnect!
       end
 
       if ActiveRecord::VERSION::MAJOR < 3
-        
-        def jdbc_insert(sql, name = nil, pk = nil, id_value = nil, sequence_name = nil, binds = [])  # :nodoc:
-          insert_sql(sql, name, pk, id_value, sequence_name, binds)
+
+        # @private
+        def jdbc_insert(sql, name = nil, pk = nil, id_value = nil, sequence_name = nil)
+          insert_sql(sql, name, pk, id_value, sequence_name)
         end
         alias_chained_method :insert, :query_dirty, :jdbc_insert
-        
-        def jdbc_update(sql, name = nil, binds = []) # :nodoc:
+
+        # @private
+        def jdbc_update(sql, name = nil, binds = [])
           execute(sql, name, binds)
         end
         alias_chained_method :update, :query_dirty, :jdbc_update
-        
-        def jdbc_select_all(sql, name = nil, binds = []) # :nodoc:
+
+        # @private
+        def jdbc_select_all(sql, name = nil, binds = [])
           select(sql, name, binds)
         end
         alias_chained_method :select_all, :query_cache, :jdbc_select_all
-        
+
+      end
+
+      # @note Used on AR 2.3 and 3.0
+      # @override
+      def insert_sql(sql, name = nil, pk = nil, id_value = nil, sequence_name = nil)
+        id = execute(sql, name)
+        id_value || id
       end
-      
+
       def columns(table_name, name = nil)
         @connection.columns(table_name.to_s)
       end
-      
-      # Executes +sql+ statement in the context of this connection using
-      # +binds+ as the bind substitutes.  +name+ is logged along with
-      # the executed +sql+ statement.
-      def exec_query(sql, name = 'SQL', binds = []) # :nodoc:
-        sql = to_sql(sql, binds)
+
+      # Starts a database transaction.
+      # @override
+      def begin_db_transaction
+        @connection.begin
+      end
+
+      # Commits the current database transaction.
+      # @override
+      def commit_db_transaction
+        @connection.commit
+      end
+
+      # Rolls back the current database transaction.
+      # @override
+      def rollback_db_transaction
+        @connection.rollback
+      end
+
+      # Starts a database transaction.
+      # @param isolation the transaction isolation to use
+      # @since 1.3.0
+      # @override on **AR-4.0**
+      def begin_isolated_db_transaction(isolation)
+        @connection.begin(isolation)
+      end
+
+      # Does this adapter support setting the isolation level for a transaction?
+      # Unlike 'plain' `ActiveRecord` we allow checking for concrete transaction
+      # isolation level support by the database.
+      # @param level optional to check if we support a specific isolation level
+      # @since 1.3.0
+      # @extension added optional level parameter
+      def supports_transaction_isolation?(level = nil)
+        @connection.supports_transaction_isolation?(level)
+      end
+
+      # Does our database (+ its JDBC driver) support save-points?
+      # @since 1.3.0
+      # @override
+      def supports_savepoints?
+        @connection.supports_savepoints?
+      end
+
+      # Creates a (transactional) save-point one can rollback to.
+      # Unlike 'plain' `ActiveRecord` it is allowed to pass a save-point name.
+      # @param name the save-point name
+      # @return save-point name (even if nil passed will be generated)
+      # @since 1.3.0
+      # @extension added optional name parameter
+      def create_savepoint(name = current_savepoint_name(true))
+        @connection.create_savepoint(name)
+      end
+
+      # Transaction rollback to a given (previously created) save-point.
+      # If no save-point name given rollback to the last created one.
+      # @param name the save-point name
+      # @since 1.3.0
+      # @extension added optional name parameter
+      def rollback_to_savepoint(name = current_savepoint_name)
+        @connection.rollback_savepoint(name)
+      end
+
+      # Release a previously created save-point.
+      # @note Save-points are auto-released with the transaction they're created
+      # in (on transaction commit or roll-back).
+      # @param name the save-point name
+      # @since 1.3.0
+      # @extension added optional name parameter
+      def release_savepoint(name = current_savepoint_name)
+        @connection.release_savepoint(name)
+      end
+
+      # Due tracking of save-points created in a LIFO manner, always returns
+      # the correct name if any (last) save-point has been marked and not released.
+      # Otherwise when creating a save-point same naming convention as
+      # `ActiveRecord` uses ("active_record_" prefix) will be returned.
+      # @return [String] the current save-point name
+      # @since 1.3.0
+      # @override
+      def current_savepoint_name(create = nil)
+        return "active_record_#{open_transactions}" if create
+        @connection.marked_savepoint_names.last || "active_record_#{open_transactions}"
+      end
+
+      # Executes a SQL query in the context of this connection using the bind
+      # substitutes.
+      # @param sql the query string (or AREL object)
+      # @param name logging marker for the executed SQL statement log entry
+      # @param binds the bind parameters
+      # @return [ActiveRecord::Result] or [Array] on **AR-2.3**
+      # @override available since **AR-3.1**
+      def exec_query(sql, name = 'SQL', binds = [])
         if prepared_statements?
           log(sql, name, binds) { @connection.execute_query(sql, binds) }
         else
@@ -305,35 +421,59 @@ module ActiveRecord
         end
       end
 
-      # Executes insert +sql+ statement in the context of this connection using
-      # +binds+ as the bind substitutes. +name+ is the logged along with
-      # the executed +sql+ statement.
-      def exec_insert(sql, name, binds, pk = nil, sequence_name = nil) # :nodoc:
-        sql = suble_binds to_sql(sql, binds), binds
-        log(sql, name || 'SQL') { @connection.execute_insert(sql) }
+      # Executes an insert statement in the context of this connection.
+      # @param sql the query string (or AREL object)
+      # @param name logging marker for the executed SQL statement log entry
+      # @param binds the bind parameters
+      # @override available since **AR-3.1**
+      def exec_insert(sql, name, binds, pk = nil, sequence_name = nil)
+        if prepared_statements?
+          log(sql, name || 'SQL', binds) { @connection.execute_insert(sql, binds) }
+        else
+          sql = suble_binds sql, binds
+          log(sql, name || 'SQL') { @connection.execute_insert(sql) }
+        end
       end
 
-      # Executes delete +sql+ statement in the context of this connection using
-      # +binds+ as the bind substitutes. +name+ is the logged along with
-      # the executed +sql+ statement.
-      def exec_delete(sql, name, binds) # :nodoc:
-        sql = suble_binds to_sql(sql, binds), binds
-        log(sql, name || 'SQL') { @connection.execute_delete(sql) }
+      # Executes a delete statement in the context of this connection.
+      # @param sql the query string (or AREL object)
+      # @param name logging marker for the executed SQL statement log entry
+      # @param binds the bind parameters
+      # @override available since **AR-3.1**
+      def exec_delete(sql, name, binds)
+        if prepared_statements?
+          log(sql, name || 'SQL', binds) { @connection.execute_delete(sql, binds) }
+        else
+          sql = suble_binds sql, binds
+          log(sql, name || 'SQL') { @connection.execute_delete(sql) }
+        end
       end
 
-      # Executes update +sql+ statement in the context of this connection using
-      # +binds+ as the bind substitutes. +name+ is the logged along with
-      # the executed +sql+ statement.
-      def exec_update(sql, name, binds) # :nodoc:
-        sql = suble_binds to_sql(sql, binds), binds
-        log(sql, name || 'SQL') { @connection.execute_update(sql) }
+      # # Executes an update statement in the context of this connection.
+      # @param sql the query string (or AREL object)
+      # @param name logging marker for the executed SQL statement log entry
+      # @param binds the bind parameters
+      # @override available since **AR-3.1**
+      def exec_update(sql, name, binds)
+        if prepared_statements?
+          log(sql, name || 'SQL', binds) { @connection.execute_update(sql, binds) }
+        else
+          sql = suble_binds sql, binds
+          log(sql, name || 'SQL') { @connection.execute_update(sql) }
+        end
       end
-      
+
       # Similar to {#exec_query} except it returns "raw" results in an array
-      # where each rows is a hash with keys as columns (just like Rails used to 
+      # where each rows is a hash with keys as columns (just like Rails used to
       # do up until 3.0) instead of wrapping them in a {#ActiveRecord::Result}.
-      def exec_query_raw(sql, name = 'SQL', binds = [], &block) # :nodoc:
-        sql = to_sql(sql, binds)
+      # @param sql the query string (or AREL object)
+      # @param name logging marker for the executed SQL statement log entry
+      # @param binds the bind parameters
+      # @yield [v1, v2] depending on the row values returned from the query
+      # In case a block is given it will yield each row from the result set
+      # instead of returning mapped query results in an array.
+      # @return [Array] unless a block is given
+      def exec_query_raw(sql, name = 'SQL', binds = [], &block)
         if prepared_statements?
           log(sql, name, binds) { @connection.execute_query_raw(sql, binds, &block) }
         else
@@ -341,252 +481,321 @@ module ActiveRecord
           log(sql, name) { @connection.execute_query_raw(sql, &block) }
         end
       end
-      
+
+      # @private
+      # @override
       def select_rows(sql, name = nil)
         exec_query_raw(sql, name).map!(&:values)
       end
-      
+
       if ActiveRecord::VERSION::MAJOR > 3 # expects AR::Result e.g. from select_all
-        
+
+      # @private
       def select(sql, name = nil, binds = [])
-        exec_query(sql, name, binds)
+        exec_query(to_sql(sql, binds), name, binds)
       end
-        
+
       else
-        
+
+      # @private
       def select(sql, name = nil, binds = []) # NOTE: only (sql, name) on AR < 3.1
-        exec_query_raw(sql, name, binds)
+        exec_query_raw(to_sql(sql, binds), name, binds)
       end
-      
+
       end
-      
-      if ActiveRecord::VERSION::MAJOR < 3 # 2.3.x
-        
-      # NOTE: 2.3 log(sql, name) while does not like `name == nil`
-      
+
       # Executes the SQL statement in the context of this connection.
-      def execute(sql, name = nil, binds = [])
-        sql = suble_binds to_sql(sql, binds), binds
+      # The return value from this method depends on the SQL type (whether
+      # it's a SELECT, INSERT etc.). For INSERTs a generated id might get
+      # returned while for UPDATE statements the affected row count.
+      # Please note that this method returns "raw" results (in an array) for
+      # statements that return a result set, while {#exec_query} is expected to
+      # return a `ActiveRecord::Result` (since AR 3.1).
+      # @note This method does not use prepared statements.
+      # @see #exec_query
+      # @see #exec_insert
+      # @see #exec_update
+      def execute(sql, name = nil, binds = nil)
+        sql = suble_binds to_sql(sql, binds), binds if binds
         if name == :skip_logging
           _execute(sql, name)
         else
-          log(sql, name ||= 'SQL') { _execute(sql, name) }
+          log(sql, name) { _execute(sql, name) }
         end
       end
 
-      else
-      #elsif ActiveRecord::VERSION::MAJOR == 3 && ActiveRecord::VERSION::MINOR == 0
-      
-      # NOTE: 3.0 log(sql, name) allow `name == nil` (handles `name ||= "SQL"`)
-      
-      # Executes the SQL statement in the context of this connection.
-      def execute(sql, name = nil, binds = [])
-        sql = suble_binds to_sql(sql, binds), binds
-        if name == :skip_logging
+      # @private documented above
+      def execute(sql, name = nil, skip_logging = false)
+        if skip_logging.is_a?(Array)
+          binds, skip_logging = skip_logging, false
+          sql = suble_binds to_sql(sql, binds), binds
+        end
+        if skip_logging || name == :skip_logging
           _execute(sql, name)
         else
           log(sql, name) { _execute(sql, name) }
         end
-      end
-
-      # NOTE: 3.1 log(sql, name = "SQL", binds = []) `name == nil` is fine
-      # TODO skip logging the binds (twice) until prepared-statement support
-      
-      #else
-      end
-
-      # we need to do it this way, to allow Rails stupid tests to always work
-      # even if we define a new execute method. Instead of mixing in a new
-      # execute, an _execute should be mixed in.
+      end if ActiveRecord::VERSION::MAJOR < 3 ||
+        ( ActiveRecord::VERSION::MAJOR == 3 && ActiveRecord::VERSION::MINOR == 0 )
+
+      # We need to do it this way, to allow Rails stupid tests to always work
+      # even if we define a new `execute` method. Instead of mixing in a new
+      # `execute`, an `_execute` should be mixed in.
+      # @deprecated it was only introduced due tests
+      # @private
       def _execute(sql, name = nil)
         @connection.execute(sql)
       end
       private :_execute
 
-      # NOTE: we have an extra binds argument at the end due 2.3 support (due {#jdbc_insert}).
-      def insert_sql(sql, name = nil, pk = nil, id_value = nil, sequence_name = nil, binds = []) # :nodoc:
-        id = execute(sql, name = nil, binds)
-        id_value || id
-      end
-
+      # @override
       def tables(name = nil)
         @connection.tables
       end
 
+      # @override
       def table_exists?(name)
         @connection.table_exists?(name) # schema_name = nil
       end
 
+      # @override
       def indexes(table_name, name = nil, schema_name = nil)
         @connection.indexes(table_name, name, schema_name)
       end
 
-      def begin_db_transaction
-        @connection.begin
+      # @override
+      def pk_and_sequence_for(table)
+        ( key = primary_key(table) ) ? [ key, nil ] : nil
       end
 
-      def commit_db_transaction
-        @connection.commit
+      # @override
+      def primary_key(table)
+        primary_keys(table).first
       end
 
-      def rollback_db_transaction
-        @connection.rollback
+      # @override
+      def primary_keys(table)
+        @connection.primary_keys(table)
       end
 
-      def begin_isolated_db_transaction(isolation)
-        @connection.begin(isolation)
-      end
-      
-      # Does this adapter support setting the isolation level for a transaction?
-      # @note We allow to ask for a specified transaction isolation level ...
-      def supports_transaction_isolation?(level = nil)
-        @connection.supports_transaction_isolation?(level)
-      end 
-      
+      # @deprecated use {#update_lob_value} instead
       def write_large_object(*args)
         @connection.write_large_object(*args)
       end
 
-      def pk_and_sequence_for(table)
-        key = primary_key(table)
-        [ key, nil ] if key
-      end
-
-      def primary_key(table)
-        primary_keys(table).first
-      end
-
-      def primary_keys(table)
-        @connection.primary_keys(table)
+      def update_lob_value(record, column, value)
+        @connection.update_lob_value(record, column, value)
       end
 
       if ActiveRecord::VERSION::MAJOR == 3 && ActiveRecord::VERSION::MINOR == 0
-      
+
         #attr_reader :visitor unless method_defined?(:visitor) # not in 3.0
-        
-        # Converts an AREL AST to SQL.
-        def to_sql(arel, binds = [])
+
+        # @private
+        def to_sql(arel, binds = nil)
           # NOTE: can not handle `visitor.accept(arel.ast)` right
           arel.respond_to?(:to_sql) ? arel.send(:to_sql) : arel
         end
-        
-      elsif ActiveRecord::VERSION::MAJOR >= 3 # AR >= 3.1 or 4.0
-        
-        # Converts an AREL AST to SQL.
+
+      elsif ActiveRecord::VERSION::MAJOR < 3 # AR-2.3 'fake' #to_sql method
+
+        # @private
+        def to_sql(sql, binds = nil)
+          sql
+        end
+
+      else # AR >= 3.1 or 4.0
+
+        # @private
         def to_sql(arel, binds = [])
+          # NOTE: same on 3.1/3.2 but on 4.0 binds are dup-ed
+          # for us it is intentional to 'consume' (empty) the binds array
+          # due our {#suble_binds} hack (that will be getting deprecated)
           if arel.respond_to?(:ast)
-            visitor.accept(arel.ast) { quote(*binds.shift.reverse) }
+            visitor.accept(arel.ast) do
+              quote(*binds.shift.reverse)
+            end
           else
             arel
           end
         end
-      
-      else # AR-2.3 no #to_sql method
-        
-        def to_sql(sql, binds = nil)
-          sql
-        end
-        
+
       end
-      
+
       protected
- 
+
+      # @override so that we do not have to care having 2 arguments on 3.0
+      def log(sql, name = nil, binds = [])
+        unless binds.blank?
+          binds = binds.map do |column, value|
+            column ? [column.name, value] : [nil, value]
+          end
+          sql = "#{sql} #{binds.inspect}"
+        end
+        super(sql, name || 'SQL') # `log(sql, name)` on AR <= 3.0
+      end if ActiveRecord::VERSION::MAJOR < 3 ||
+        ( ActiveRecord::VERSION::MAJOR == 3 && ActiveRecord::VERSION::MINOR < 1 )
+
       def translate_exception(e, message)
         # we shall not translate native "Java" exceptions as they might
         # swallow an ArJdbc / driver bug into a AR::StatementInvalid ...
         return e if e.is_a?(NativeException) # JRuby 1.6
         return e if e.is_a?(Java::JavaLang::Throwable)
-        super # NOTE: wraps AR::JDBCError into AR::StatementInvalid, desired ?!
+
+        case e
+        when SystemExit, SignalException, NoMemoryError then e
+        # NOTE: wraps AR::JDBCError into AR::StatementInvalid, desired ?!
+        else super
+        end
       end
 
+      # Take an id from the result of an INSERT query.
+      # @return [Integer, NilClass]
       def last_inserted_id(result)
-        result
+        if result.is_a?(Hash) || result.is_a?(ActiveRecord::Result)
+          result.first.first[1] # .first = { "id"=>1 } .first = [ "id", 1 ]
+        else
+          result
+        end
       end
-      
-      # Helper to handle 3.x/4.0 uniformly override #table_definition as :
-      # 
+
+      # @private
+      def last_inserted_id(result)
+        if result.is_a?(Hash)
+          result.first.first[1] # .first = { "id"=>1 } .first = [ "id", 1 ]
+        else
+          result
+        end
+      end unless defined? ActiveRecord::Result
+
+      # Helper to easily override #table_definition (on AR 3.x/4.0) as :
+      # ```
       #   def table_definition(*args)
       #     new_table_definition(TableDefinition, *args)
       #   end
-      #
+      # ```
       def new_table_definition(table_definition, *args)
         table_definition.new(self) # args ignored only used for 4.0
       end
       private :new_table_definition
-      
-      # if adapter overrides #table_definition it works on 3.x as well as 4.0
+
+      # NOTE: make sure if adapter overrides #table_definition that it will
+      # work on AR 3.x as well as 4.0
       if ActiveRecord::VERSION::MAJOR > 3
-        
+
       # aliasing #create_table_definition as #table_definition :
       alias table_definition create_table_definition
 
-      # TableDefinition.new native_database_types, name, temporary, options
+      # `TableDefinition.new native_database_types, name, temporary, options`
+      # @private
       def create_table_definition(name, temporary, options)
         table_definition(name, temporary, options)
       end
-      
-      # arguments expected: (name, temporary, options)
+
+      # @note AR-4x arguments expected: `(name, temporary, options)`
+      # @private documented above
       def new_table_definition(table_definition, *args)
         table_definition.new native_database_types, *args
       end
       private :new_table_definition
-      
+
       end
-    
-      private
-      
+
+      # @return whether `:prepared_statements` are to be used
       def prepared_statements?
-        self.class.prepared_statements?(config)
+        return @prepared_statements unless (@prepared_statements ||= nil).nil?
+        @prepared_statements = self.class.prepared_statements?(config)
       end
-    
+
+      # Allows changing the prepared statements setting for this connection.
+      # @see #prepared_statements?
+      #def prepared_statements=(statements)
+      #  @prepared_statements = statements
+      #end
+
+      private
+
       def self.prepared_statements?(config)
         config.key?(:prepared_statements) ?
           type_cast_config_to_boolean(config.fetch(:prepared_statements)) :
-            false # NOTE: off by default for now
+            false # off by default
       end
 
       def suble_binds(sql, binds)
         return sql if binds.nil? || binds.empty?
         copy = binds.dup
+        # TODO deprecate/warn about this behavior !
         sql.gsub('?') { quote(*copy.shift.reverse) }
       end
-      
-      # @deprecated replaced with {#suble_binds}
+
+      # @deprecated Replaced with {#suble_binds}.
       def substitute_binds(sql, binds)
         suble_binds(extract_sql(sql), binds)
       end
 
-      # @deprecated no longer used
+      # @deprecated No longer used, only kept for 1.2 API compatibility.
       def extract_sql(obj)
         obj.respond_to?(:to_sql) ? obj.send(:to_sql) : obj
       end
-      
+
+      # Helper to get local/UTC time (based on `ActiveRecord::Base.default_timezone`).
+      def get_time(value)
+        get = ::ActiveRecord::Base.default_timezone == :utc ? :getutc : :getlocal
+        value.respond_to?(get) ? value.send(get) : value
+      end
+
       protected
-      
+
+      # @return whether the given SQL string is a 'SELECT' like
+      # query (returning a result set)
       def self.select?(sql)
         JdbcConnection::select?(sql)
       end
 
+      # @return whether the given SQL string is an 'INSERT' query
       def self.insert?(sql)
         JdbcConnection::insert?(sql)
       end
 
+      # @return whether the given SQL string is an 'UPDATE' (or 'DELETE') query
       def self.update?(sql)
         ! select?(sql) && ! insert?(sql)
       end
-      
+
       unless defined? AbstractAdapter.type_cast_config_to_integer
-        
+
+        # @private
         def self.type_cast_config_to_integer(config)
           config =~ /\A\d+\z/ ? config.to_i : config
         end
 
+        # @private
         def self.type_cast_config_to_boolean(config)
           config == "false" ? false : config
         end
-        
+
+      end
+
+      public
+
+      # @note Used by Java API to convert dates from (custom) SELECTs (might get refactored).
+      # @private
+      def _string_to_date(value)
+        jdbc_column_class.string_to_date(value)
       end
-      
+
+      # @note Used by Java API to convert times from (custom) SELECTs (might get refactored).
+      # @private
+      def _string_to_time(value)
+        jdbc_column_class.string_to_dummy_time(value)
+      end
+
+      # @note Used by Java API to convert times from (custom) SELECTs (might get refactored).
+      # @private
+      def _string_to_timestamp(value)
+        jdbc_column_class.string_to_time(value)
+      end
+
     end
   end
 end