jdbc-helper 0.7.6 → 0.7.7

data/CHANGELOG.markdown

@@ -1,3 +1,11 @@
+### 0.7.7 / 2013/01/0?
+* `PreparedStatment`s and `TableWrapper`s now inherit the fetch size of the connection
+* Added `JDBCHelper::TableWrapper#fetch_size`
+* Added `JDBCHelper::TableWrapper#execute_batch`
+* Added `JDBCHelper::TableWrapper#clear_batch`
+* `execute_batch` method returns the sum of all update counts
+* Removed undocumented operation statistics
+
 ### 0.7.6 / 2012/08/26
 * Added FileMaker Pro connector (statonjr)
 

data/README.markdown

@@ -108,13 +108,16 @@ conn.query("SELECT a, b, c FROM T") do |row|
   row.labels
   row.rownum
 
-  row.a, row.b, row.c          # Dot-notation
-  row[0], row[1], row[2]       # Numeric index
-  row['a'], row['b'], row['c'] # String index. Case-insensitive.
-  row[:a], row[:b], row[:c]    # Symbol index. Case-insensitive.
+  a, b, c = row
+  a, b, c = row.a,    row.b,    row.c    # Dot-notation
+  a, b, c = row[0],   row[1],   row[2]   # Numeric index
+  a, b, c = row['a'], row['b'], row['c'] # String index. Case-insensitive.
+  a, b, c = row[:a],  row[:b],  row[:c]  # Symbol index. Case-insensitive.
 
   row[0..-1]                   # Range index. Returns an array of values.
   row[0, 3]                    # Offset and length. Returns an array of values.
+
+  row.to_h                     # Row as a Hash
 end
 
 # Returns an array of rows when block is not given
@@ -199,6 +202,15 @@ p_upd.execute_batch
 p_upd.close
 ```
 
+### Accessing underlying Java object with `java` method
+
+```ruby
+conn.java.setAutoCommit false
+
+pstmt = conn.prepare(sql)
+pstmt.java.getMetaData
+```
+
 ### Using table wrappers (since 0.2.0)
 ```ruby
 # For more complex examples, refer to test/test_object_wrapper.rb
@@ -206,6 +218,8 @@ SQL = JDBCHelper::SQL
 
 # Creates a table wrapper
 table = conn.table('test.data')
+# Or equievalently,
+table = conn['test.data']
 
 # Counting the records in the table
 table.count
@@ -215,8 +229,8 @@ table.where(:a => 10).count
 table.empty?
 table.where(:a => 10).empty?
 
-# Selects the table by combining select, where, and order methods
-table.select('a apple', :b).where(:c => (1..10)).order('b desc', 'a asc') do |row|
+# Selects the table by combining select, where, order and fetch_size methods
+table.select('a apple', :b).where(:c => (1..10)).order('b desc', 'a asc').fetch_size(100).each do |row|
   puts row.apple
 end
 
@@ -239,7 +253,8 @@ with_defaults.where('a != 10 or b != 20').update   # sets a => 10, b => 20
 # Batch updates with batch method
 table.batch.insert(:a => 10, :b => 20, :c => SQL.expr('10 + 20'))
 table.batch.insert_ignore(:a => 10, :b => 20, :c => 30)
-conn.execute_batch
+table.batch.where(:a => 10).update(:a => 20)
+table.execute_batch :insert, :update
 
 # Delete with conditions
 table.delete(:c => 3)
@@ -275,27 +290,48 @@ scope = table.where(
 scope.update(:a => 'xyz')
 ```
 
-#### Invalid use of dynamic conditions
+#### Invalid use of plain String conditions
 
-TableWrapper object internally creates JDBC PreparedStatements.
-If you dynamically build many condition-strings as the following example,
-it would soon fail because there will be too many open PreparedStatements.
+A TableWrapper object internally builds SQL strings
+and creates JDBC PreparedStatement object for each distinct SQL.
+
+If you build many number of where-clause Strings as shown in the following code,
+soon there will be too many open PreparedStatements,
+and if the number exceeds the system limit, an error will be thrown.
 
 ```ruby
+table = connection['table']
+
+# Leads to 10000 PreparedStatements !!
 10000.times do |idx|
   table.count("id = #{idx}")
+    # select count(*) from table where id = 0
+    # select count(*) from table where id = 1
+    # select count(*) from table where id = 2
+    # select count(*) from table where id = 3
+    # ...
 end
 ```
 
-Correct ways of doing the same would be as follows.
+In that case, you can `close` the table wrapper to close all the open PreparedStatements.
+
+```ruby
+table.close
+```
+
+However, you should always prefer using much more efficient Hash or Array expression over plain String,
+so you don't have to worry about the proliferation of PreparedStatements.
 
 ```ruby
+# 20000 queries but only a single PreparedStatement
 10000.times do |idx|
   # 1. with Hash
   table.count('id' => idx)
+    # select count(*) from table where id = ?
 
   # 2. with Array
   table.count(["id = ?", idx])
+    # select count(*) from table where id = ?
 end
 ```
 

data/Rakefile

@@ -14,11 +14,3 @@ Rake::TestTask.new(:performance) do |test|
   test.verbose = true
 end
 
-require 'rcov/rcovtask'
-Rcov::RcovTask.new do |test|
-  test.libs << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.rcov_opts << '--exclude rcov'
-  test.verbose = true
-end
-

data/jdbc-helper.gemspec

@@ -15,8 +15,8 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = JDBCHelper::VERSION
 
-  gem.add_runtime_dependency 'insensitive_hash', '>= 0.2.4', '< 0.4.0'
-  gem.add_development_dependency "bundler", "~> 1.1.4"
-  gem.add_development_dependency "rcov", "~> 0.9"
-  gem.add_development_dependency "test-unit", ">= 2.3.0"
+  gem.add_runtime_dependency 'insensitive_hash', '>= 0.2.4'
+  gem.add_development_dependency "bundler"
+  gem.add_development_dependency "simplecov"
+  gem.add_development_dependency "test-unit"
 end

data/lib/jdbc-helper/connection.rb

@@ -25,17 +25,17 @@ module JDBCHelper
 # @example Prerequisites
 #  # Add JDBC driver of the DBMS you're willing to use to your CLASSPATH
 #  export CLASSPATH=$CLASSPATH:~/lib/mysql-connector-java.jar
-# 
-# 
+#
+#
 # @example Connecting to a database
-# 
+#
 #  # :driver and :url must be given
 #  conn = JDBCHelper::Connection.new(
 #               :driver => 'com.mysql.jdbc.Driver',
 #               :url    => 'jdbc:mysql://localhost/test')
 #  conn.close
-#  
-#  
+#
+#
 #  # Optional :user and :password
 #  conn = JDBCHelper::Connection.new(
 #               :driver   => 'com.mysql.jdbc.Driver',
@@ -43,12 +43,12 @@ module JDBCHelper
 #               :user     => 'mysql',
 #               :password => '')
 #  conn.close
-#  
-#  
+#
+#
 #  # MySQL shortcut connector
 #  conn = JDBCHelper::MySQLConnector.connect('localhost', 'mysql', '', 'test')
 #  conn.close
-#  
+#
 # @example Querying database table
 #
 #  conn.query("SELECT a, b, c FROM T") do | row |
@@ -59,11 +59,11 @@ module JDBCHelper
 #      puts row[0], row[1], row[2]
 #      puts row['a'], row['b'], row['c']
 #  end
-# 
+#
 #  # Returns an array of rows when block is not given
 #  rows = conn.query("SELECT b FROM T")
 #  uniq_rows = rows.uniq
-# 
+#
 #  # You can even nest queries
 #  conn.query("SELECT a FROM T") do | row1 |
 #      conn.query("SELECT * FROM T_#{row1.a}") do | row2 |
@@ -72,26 +72,26 @@ module JDBCHelper
 #  end
 # @example Updating database table
 #  del_count = conn.update("DELETE FROM T")
-# 
+#
 # @example Transaction
 #  committed = conn.transaction do | tx |
 #      # ...
 #      # Transaction logic here
 #      # ...
-#  
+#
 #      if success
 #          tx.commit
 #      else
 #          tx.rollback
 #      end
 #  end
-# 
+#
 # @example Using batch interface
 #  conn.add_batch("DELETE FROM T");
 #  conn.execute_batch
 #  conn.add_batch("DELETE FROM T");
 #  conn.clear_batch
-#   
+#
 # @example Using prepared statements
 #  p_sel = conn.prepare("SELECT * FROM T WHERE b = ? and c = ?")
 #  p_sel.query(100, 200) do | row |
@@ -111,16 +111,6 @@ module JDBCHelper
 #  p_upd.execute_batch
 #  p_upd.close
 class Connection
-  # Returns the statistics of the previous operation
-  # @return [JDBCHelper::Connection::Stat] The statistics of the previous operation.
-  def prev_stat
-    @prev_stat.dup
-  end
-
-  # Returns the accumulated statistics of each operation
-  # @return [Hash] Accumulated statistics of each type of operation
-  attr_reader :stats
-
   # JDBC URL of the connection
   # @return [String]
   attr_reader :url
@@ -135,6 +125,7 @@ class Connection
     @conn
   end
   alias java_obj jdbc_conn
+  alias java     jdbc_conn
 
   # Creates a database connection.
   # - `args` hash must include :driver (or "driver") and :url (or "url")
@@ -163,23 +154,21 @@ class Connection
       if timeout.is_a?(Fixnum) == false || timeout <= 0
         raise ArgumentError.new("Timeout must be a positive integer")
       end
-      java.sql.DriverManager.setLoginTimeout timeout
+      Java::java.sql.DriverManager.setLoginTimeout timeout
     end
 
-    props = java.util.Properties.new
+    props = Java::java.util.Properties.new
     args.each do |k, v|
       props.setProperty(k.to_s, v.to_s) if v
     end
-    
-    @conn = java.sql.DriverManager.get_connection(@url, props)
+
+    @conn = Java::java.sql.DriverManager.get_connection(@url, props)
     @spool = StatementPool.send :new, self
     @bstmt = nil
-
-    @stats = Hash.new { | h, k | h[k] = Stat.new(k, 0, 0, 0) }
-    @prev_stat = Stat.new(nil, 0, 0, 0)
+    @fetch_size = nil
 
     @pstmts = []
-    
+
     @table_wrappers = {}
 
     if block_given?
@@ -204,8 +193,9 @@ class Connection
   def prepare(qstr)
     check_closed
 
-    pstmt = PreparedStatement.send(:new, self, qstr,
-        measure_exec(:prepare) { @conn.prepare_statement(qstr) })
+    pstmt = PreparedStatement.send(:new, self, qstr, @conn.prepare_statement(qstr))
+    pstmt.set_fetch_size @fetch_size if @fetch_size
+
     @pstmts << pstmt
     pstmt
   end
@@ -220,8 +210,7 @@ class Connection
   def prepare_call(qstr)
     check_closed
 
-    CallableStatement.send(:new, self, qstr,
-        measure_exec(:prepare_call) { @conn.prepare_call qstr })
+    CallableStatement.send(:new, self, qstr, @conn.prepare_call(qstr))
   end
 
   # Executes the given code block as a transaction. Returns true if the transaction is committed.
@@ -252,7 +241,7 @@ class Connection
     status == :committed
   end
 
-  # Executes an SQL and returns the count of the update rows or a ResultSetEnumerator object 
+  # Executes an SQL and returns the count of the update rows or a ResultSetEnumerator object
   # depending on the type of the given statement.
   # If a ResultSetEnumerator is returned, it must be enumerated or closed.
   # @param [String] qstr SQL string
@@ -262,7 +251,7 @@ class Connection
 
     stmt = @spool.take
     begin
-      if measure_exec(:execute) { stmt.execute(qstr) }
+      if stmt.execute(qstr)
         ResultSetEnumerator.send(:new, stmt.getResultSet) { @spool.give stmt }
       else
         rset = stmt.getUpdateCount
@@ -282,7 +271,7 @@ class Connection
     check_closed
 
     @spool.with do | stmt |
-      ret = measure_exec(:update) { stmt.execute_update(qstr) }
+      ret = stmt.execute_update(qstr)
     end
   end
 
@@ -306,7 +295,7 @@ class Connection
     check_closed
 
     @spool.with do | stmt |
-      rset = measure_exec(:query) { stmt.execute_query(qstr) }
+      rset = stmt.execute_query(qstr)
       process_and_close_rset(rset, &blk)
     end
   end
@@ -332,7 +321,7 @@ class Connection
 
     stmt = @spool.take
     begin
-      rset = measure_exec(:query) { stmt.execute_query(qstr) }
+      rset = stmt.execute_query(qstr)
       return ResultSetEnumerator.send(:new, rset) { @spool.give stmt }
     rescue Exception
       @spool.give stmt
@@ -351,20 +340,24 @@ class Connection
     @bstmt.add_batch qstr
   end
 
-  # Executes batched statements including prepared statements. No effect when no statment is added
-  # @return [NilClass]
+  # Executes batched statements including prepared statements. No effect when no statement is added
+  # @return [Fixnum] Sum of all update counts
   def execute_batch
     check_closed
 
+    cnt = 0
+
     if @bstmt
-      measure_exec(:execute_batch) { @bstmt.execute_batch }
+      cnt += @bstmt.execute_batch.inject(:+) || 0
       @spool.give @bstmt
       @bstmt = nil
     end
 
-    @pstmts.each do |stmt|
-      measure_exec(:execute_batch) { stmt.execute_batch }
+    @pstmts.each do |pstmt|
+      cnt += pstmt.execute_batch
     end
+
+    cnt
   end
 
   # Clears the batched statements including prepared statements.
@@ -379,7 +372,7 @@ class Connection
     end
 
     @pstmts.each do |stmt|
-      measure_exec(:execute_batch) { stmt.clear_batch }
+      stmt.clear_batch
     end
   end
 
@@ -419,8 +412,11 @@ class Connection
   # @param [String/Symbol] table_name Name of the table to be wrapped
   # @return [JDBCHelper::TableWrapper]
   def table table_name
-    @table_wrappers[table_name] ||= JDBCHelper::TableWrapper.new self, table_name
+    table = JDBCHelper::TableWrapper.new(self, table_name)
+    table = table.fetch_size(@fetch_size) if @fetch_size
+    @table_wrappers[table_name] ||= table
   end
+  alias [] table
 
   # Returns a sequence wrapper for the given name
   # @since 0.4.2
@@ -446,24 +442,13 @@ class Connection
     JDBCHelper::ProcedureWrapper.new self, proc_name
   end
 
+  # @return [String]
   def inspect
     InsensitiveHash[@args].merge({ :closed? => closed? }).tap { |c|
       c.delete(:password)
     }.inspect
   end
 
-  # Statistics
-  class Stat
-    attr_accessor :type, :elapsed, :success_count, :fail_count
-
-    def initialize(t, e, s, f)
-      self.type          = t
-      self.elapsed       = e
-      self.success_count = s
-      self.fail_count    = f
-    end
-  end
-
 private
   # Transaction object passed to the code block given to transaction method
   class Transaction
@@ -479,7 +464,7 @@ private
       @conn.rollback
       raise Rollback
     end
-  private  
+  private
     def initialize(conn) # :nodoc:
       @conn = conn
     end
@@ -517,31 +502,6 @@ private
     @pstmts.delete pstmt
   end
 
-  def update_stat(type, elapsed, success_count, fail_count) # :nodoc:
-    @prev_stat.type          = type
-    @prev_stat.elapsed       = elapsed
-    @prev_stat.success_count = success_count
-    @prev_stat.fail_count    = fail_count
-
-    accum                = @stats[type]
-    accum.elapsed       += elapsed
-    accum.success_count += success_count
-    accum.fail_count    += fail_count
-  end
-
-  def measure_exec(type)
-    begin
-      st      = Time.now
-      ret     = yield
-      elapsed = Time.now - st
-      update_stat(type, elapsed, 1, 0)
-    rescue Exception
-      update_stat(type, 0, 0, 1)
-      raise
-    end
-    ret
-  end
-  
   def check_closed
     raise RuntimeError.new('Connection already closed') if closed?
   end