jdbc-helper 0.2.1 → 0.3.0

data/README.rdoc

@@ -6,14 +6,14 @@ crucial database operations from primitive selects and updates to more complex o
 batch updates, prepared statements and transactions.
 As the name implies, this gem only works on JRuby.
 
-= Examples
+== Examples
 
-== Prerequisites
+=== Prerequisites
 Add JDBC driver of the DBMS you're willing to use to your CLASSPATH
  export CLASSPATH=$CLASSPATH:~/lib/mysql-connector-java.jar
 
 
-== Connecting to a database
+=== Connecting to a database
 
  # :driver and :url must be given
  conn = JDBCHelper::Connection.new(
@@ -35,7 +35,7 @@ Add JDBC driver of the DBMS you're willing to use to your CLASSPATH
  conn = JDBCHelper::MySQLConnector.connect('localhost', 'mysql', '', 'test')
  conn.close
 
-== Querying database table
+=== Querying database table
 
  conn.query("SELECT a, b, c FROM T") do | row |
      row.labels
@@ -71,10 +71,10 @@ Add JDBC driver of the DBMS you're willing to use to your CLASSPATH
     end
  end
 
-== Updating database table
+=== Updating database table
  del_count = conn.update("DELETE FROM T")
 
-== Transaction
+=== Transaction
  committed = conn.transaction do | tx |
      # ...
      # Transaction logic here
@@ -87,13 +87,13 @@ Add JDBC driver of the DBMS you're willing to use to your CLASSPATH
      end
  end
 
-== Using batch interface
+=== Using batch interface
  conn.add_batch("DELETE FROM T");
  conn.execute_batch
  conn.add_batch("DELETE FROM T");
  conn.clear_batch
 
-== Using prepared statements
+=== Using prepared statements
  p_sel = conn.prepare("SELECT * FROM T WHERE b = ? and c = ?")
  p_sel.query(100, 200) do | row |
      p row
@@ -112,21 +112,82 @@ Add JDBC driver of the DBMS you're willing to use to your CLASSPATH
  p_upd.execute_batch
  p_upd.close
 
-== Using table wrappers (since 0.2.0)
+=== Using table wrappers (since 0.2.0)
   # For more complex examples, refer to test/test_object_wrapper.rb
 
-  conn.table('test.data').count
-  conn.table('test.data').empty?
-  conn.table('test.data').select(:c => 3) do |row|
+  table = conn.table('test.data')
+  table.count
+  table.empty?
+  table.select(:c => 3) do |row|
     puts row.a
   end
-  conn.table('test.data').update(:a => 1, :b => 2, :where => { :c => 3 })
-  conn.table('test.data').insert(:a => 10, :b => 20, :c => 30)
-  conn.table('test.data').insert_ignore(:a => 10, :b => 20, :c => 30)
-  conn.table('test.data').replace(:a => 10, :b => 20, :c => 30)
-  conn.table('test.data').delete(:c => 3)
-  conn.table('test.data').truncate_table!
-  conn.table('test.data').drop_table!
+  table.update(:a => 1, :b => 2, :where => { :c => 3 })
+  table.insert(:a => 10, :b => 20, :c => 30)
+  table.insert_ignore(:a => 10, :b => 20, :c => 30)
+  table.replace(:a => 10, :b => 20, :c => 30)
+  table.delete(:c => 3)
+  table.truncate_table!
+  table.drop_table!
+
+=== Using function wrappers (since 0.2.2)
+  conn.function(:mod).call 5, 3
+  conn.function(:coalesce).call(nil, nil, 'king')
+
+=== Using procedure wrappers (since 0.3.0)
+  # Working with IN/INOUT/OUT parameteres
+  # Bind by ordinal number
+  conn.procedure(:update_and_fetch_something).call(
+		  100, ["value", String], Fixnum)
+
+  # Bind by parameter name
+  conn.procedure(:update_and_fetch_something).call(
+		  :a => 100, :b => ["value", String], :c => Fixnum)
+
+== Notes on vendor-independence
+
+jdbc-helper tries to be a vendor-independent library, so that it behaves the same on any RDBMS,
+and that is why it's built on JDBC in the first place which can be used to minimize the amount of vendor-specific code.
+(Ideally, one codebase for all RDBMSs.)
+So far so good, but not great. It has small amount of code that is vendor-specific, non-standard JDBC.
+And it has been confirmed to work the same for both MySQL and Oracle, except for stored procedures.
+MySQL and Oracle implement parameter binding of CallableStatement differently.
+See the following example.
+  # Let's say we have a stored procedure named my_procedure
+  # which takes 3 parameters, param1, param2, and param3.
+
+  # Creates a CallableStatemet
+  cstmt = conn.prepare_call("{call my_procedure(?, ?, ?)}")
+
+  cstmt.call(10, "ten", Fixnum)
+    # OK for both MySQL and Oracle. Filling paramters sequentially.
+
+  cstmt.call(:param1 => 10, :param2 => "ten", :param3 => Fixnum)
+    # MySQL automatically binds values by the parameter names in the original procedure definition.
+    # Oracle fails to do so.
+  cstmt.close
+
+  # For Oracle, if you prepare as follows,
+  cstmt = conn.prepare_call("{call my_procedure(:p1, :p2, :p3)}")
+
+  # Then you can do this. 
+  cstmt.call(:p1 => 10, :p2 => "ten", :p3 => Fixnum)
+    # However, p1, p2, p3 have nothing to do with the original
+    # parameter names (param1, param2, param3) in the procedure definition.
+    # They're just aliases for ordinal positions.
+    # So, it's semantically different from the first example.
+
+  cstmt.close
+
+There's no way to find out the original parameter names and their ordinal positions without looking up the metadata of the database,
+which requires having to write vendor-specific code branches, and that is definitely not desirable.
+ProcedureWrapper prepares call with '?'s as the first example. 
+So it would work fine for MySQL, but you can't use it with parameter names on Oracle.
+
+  # Good for both
+  conn.procedure(:my_procedure).call(10, "ten", Fixnum)
+
+  # Only for MySQL
+  conn.procedure(:my_procedure).call(:param1 => 10, :param2 => "ten", :param3 => Fixnum)
 
 == Contributing to jdbc-helper
 

data/lib/jdbc-helper/connection/callable_statement.rb

@@ -0,0 +1,75 @@
+# encoding: UTF-8
+# Junegunn Choi (junegunn.c@gmail.com)
+
+module JDBCHelper
+class Connection
+# Interface to Java CallableStatment
+class CallableStatement < ParameterizedStatement
+	# Array or Hash (for named parameters)
+	# - IN parameter: value
+	# - OUT parameter: class
+	# - INOUT parameter: [value, class]
+	#   (Although class can be inferred from the value, 
+	#   we still need a way to figure out if it's INOUT parameter)
+	def call *params
+		check_closed
+
+		out_params = set_params(params)
+		measure_exec(:call) { @java_obj.execute }
+
+		result = {}
+		out_params.each do |idx, jtype|
+			getter = JDBCHelper::Connection::GETTER_MAP.fetch(jtype, :get_string)
+			value = @java_obj.send(getter, idx.is_a?(Symbol) ? idx.to_s : idx)
+			result[idx] = @java_obj.was_null ? nil : value
+		end
+		result
+	end
+
+private
+	def set_params(params) # :nodoc:
+		hash_params = 
+			if params.first.kind_of? Hash
+				raise ArgumentError.new("More than one Hash given") if params.length > 1
+				params.first
+			else
+				params.each_with_index.inject({}) { |hash, pair|
+					hash[pair.last + 1] = pair.first
+					hash
+				}
+			end
+
+		out_params = {}
+		hash_params.each do | idx, value |
+			# Symbol need to be transformed into string
+
+			idx_ = idx.is_a?(Symbol) ? idx.to_s : idx
+			case value
+			# OUT parameter
+			when Class
+				jtype = JDBCHelper::Connection::RUBY_SQL_TYPE_MAP[value] || java.sql.Types::VARCHAR
+				@java_obj.registerOutParameter(idx_, jtype)
+				out_params[idx] = jtype
+
+			# INOUT parameter
+			when Array
+				set_param(idx_, value.first)
+				jtype = JDBCHelper::Connection::RUBY_SQL_TYPE_MAP[value.last] || java.sql.Types::VARCHAR
+				@java_obj.registerOutParameter(idx_, jtype)
+				out_params[idx] = jtype
+						
+			# IN parameter
+			else
+				set_param(idx_, value)
+			end
+		end
+		out_params
+	end
+
+	def initialize(*args)
+		super(*args)
+	end
+end#CallableStatment
+end#Connection
+end#JDBCHelper
+

data/lib/jdbc-helper/connection/parameterized_statement.rb

@@ -0,0 +1,64 @@
+# encoding: UTF-8
+# Junegunn Choi (junegunn.c@gmail.com)
+
+module JDBCHelper
+class Connection
+# Base class for CallableStatement and PreparedStatment
+# @abstract
+class ParameterizedStatement
+	# SQL string
+	# @return [String]
+	attr_reader :sql
+
+	# Underlying Java object
+	attr_reader :java_obj
+
+	# @param [JDBCHelper::Connection] conn
+	# @param [String] cstmt_str
+	def initialize(conn, sql, obj)
+		@conn = conn
+		@sql = sql
+		@java_obj = obj
+	end
+
+	def set_param(idx, param)
+		if param.nil?
+			@java_obj.set_null idx, java.sql.Types::NULL
+		elsif setter = JDBCHelper::Connection::SETTER_MAP[param.class.to_s]
+			if setter == :setBinaryStream
+				@java_obj.send setter, idx, param.getBinaryStream, param.length
+			elsif setter == :setTimestamp && param.is_a?(Time)
+				@java_obj.send setter, idx, java.sql.Timestamp.new(param.to_i * 1000)
+			else
+				@java_obj.send setter, idx, param
+			end
+		else
+			@java_obj.set_string idx, param.to_s
+		end
+	end
+
+	# @return [NilClass]
+	def close
+		@java_obj.close
+		@java_obj = nil
+	end
+
+	# @return [Boolean]
+	def closed?
+		@java_obj.nil?
+	end
+
+private
+	def measure_exec(type, &blk)	# :nodoc:
+		@conn.send(:measure_exec, type, &blk)
+	end
+
+	def check_closed
+		raise RuntimeError.new("Object already closed") if closed?
+	end
+
+end#ParameterizedStatement
+end#Connection
+end#JDBCHelper
+
+

data/lib/jdbc-helper/connection/prepared_statement.rb

@@ -11,20 +11,11 @@ class Connection
 #   pstmt = conn.prepare("SELECT * FROM T WHERE a = ? and b = ?")
 #   rows = pstmt.query(10, 20)
 #   enum = pstmt.enumerate(10, 20)
-class PreparedStatement
-	# SQL string
-	# @return [String]
-	attr_reader :sql
-
-	# Returns the encapsulated JDBC PreparedStatement object.
-	def java_obj
-		@pstmt
-	end
-
+class PreparedStatement < ParameterizedStatement
 	# Returns the number of parameters required
 	# @return [Fixnum]
 	def parameter_count
-		@pmd ||= @pstmt.get_parameter_meta_data
+		@pmd ||= @java_obj.get_parameter_meta_data
 		@pmd.get_parameter_count
 	end
 
@@ -33,7 +24,7 @@ class PreparedStatement
 		check_closed
 
 		set_params(params)
-		measure_exec(:p_update) { @pstmt.execute_update }
+		measure_exec(:p_update) { @java_obj.execute_update }
 	end
 
 	# @return [Array] Returns an Array if block is not given
@@ -43,7 +34,7 @@ class PreparedStatement
 		set_params(params)
 		# sorry, ignoring privacy
 		@conn.send(:process_and_close_rset,
-				   measure_exec(:p_query) { @pstmt.execute_query }, &blk)
+				   measure_exec(:p_query) { @java_obj.execute_query }, &blk)
 	end
 
 	# @return [JDBCHelper::Connection::ResultSetEnumerator]
@@ -53,7 +44,7 @@ class PreparedStatement
 		return query(*params, &blk) if block_given?
 
 		set_params(params)
-		ResultSetEnumerator.new(measure_exec(:p_query) { @pstmt.execute_query })
+		ResultSetEnumerator.new(measure_exec(:p_query) { @java_obj.execute_query })
 	end
 
 	# Adds to the batch
@@ -62,14 +53,14 @@ class PreparedStatement
 		check_closed
 
 		set_params(params)
-		@pstmt.add_batch
+		@java_obj.add_batch
 	end
 	# Executes the batch
 	def execute_batch
 		check_closed
 
 		measure_exec(:p_execute_batch) {
-			@pstmt.executeBatch
+			@java_obj.executeBatch
 		}
 	end
 	# Clears the batch
@@ -77,7 +68,7 @@ class PreparedStatement
 	def clear_batch
 		check_closed
 
-		@pstmt.clear_batch
+		@java_obj.clear_batch
 	end
 
 	# Gives the JDBC driver a hint of the number of rows to fetch from the database by a single interaction.
@@ -86,72 +77,19 @@ class PreparedStatement
 	def set_fetch_size(fsz)
 		check_closed
 
-		@pstmt.set_fetch_size fsz
+		@java_obj.set_fetch_size fsz
 	end
 
-	# Closes the prepared statement
-	# @return [NilClass]
-	def close
-		return if closed?
-		@pstmt.close
-		@pstmts.delete @sql
-		@pstmt = @pstmts = nil
-	end
-
-	# @return [Boolean]
-	def closed?
-		@pstmt.nil?
-	end
 private
-	def initialize(conn, pstmts, sql, pstmt) # :nodoc:
-		@conn = conn
-		@pstmts = pstmts
-		@sql = sql
-		@pstmt = pstmt
-	end
-
 	def set_params(params) # :nodoc:
-		idx = 0
-		params.each do | param |
-			if param.nil?
-				@pstmt.set_null(idx += 1, java.sql.Types::NULL)
-			elsif setter = SETTER_MAP[param.class.to_s]
-				if setter == :setBinaryStream
-					@pstmt.send(setter, idx += 1, param.getBinaryStream, param.length)
-				elsif setter == :setTimestamp && param.is_a?(Time)
-					@pstmt.send(setter, idx += 1, java.sql.Timestamp.new(param.to_i * 1000))
-				else
-					@pstmt.send(setter, idx += 1, param)
-				end
-			else
-				@pstmt.set_string(idx += 1, param.to_s)
-			end
+		params.each_with_index do | param, idx |
+			set_param(idx + 1, param)
 		end
 	end
 
-	def measure_exec(type, &blk)	# :nodoc:
-		@conn.send(:measure_exec, type, &blk)
-	end
-
-	def check_closed
-		raise RuntimeError.new("Prepared statement already closed") if closed?
+	def initialize(*args)
+		super(*args)
 	end
-
-	SETTER_MAP =
-	{
-		'Java::JavaSql::Date' => :setDate,
-		'Java::JavaSql::Time' => :setTime,
-		'Java::JavaSql::Timestamp' => :setTimestamp,
-		'Time'                     => :setTimestamp,
-		'Java::JavaSql::Blob' => :setBinaryStream,
-
-		# Only available when MySQL JDBC driver is loaded.
-		# So we use the string representation of the class.
-		'Java::ComMysqlJdbc::Blob' => :setBinaryStream
-
-		# FIXME-MORE
-	} # :nodoc:
-
 end#PreparedStatment
 end#Connection
 end#JDBCHelper

data/lib/jdbc-helper/connection/result_set_enumerator.rb

@@ -2,9 +2,9 @@
 # Junegunn Choi (junegunn.c@gmail.com)
 
 module JDBCHelper
-# Class for enumerating query results
-# Automatically closed after used. When not used, you must close it explicitly by calling "close".
 class Connection
+# Class for enumerating query results.
+# Automatically closed after used. When not used, you must close it explicitly by calling "close".
 class ResultSetEnumerator
 	include Enumerable
 
@@ -14,10 +14,24 @@ class ResultSetEnumerator
 		count = -1
 		begin
 			while @rset.next
+				idx = 0
+				# Oracle returns numbers in NUMERIC type, which can be of any precision.
+				# So, we retrieve the numbers in String type not to lose their precision.
+				# This can be quite annoying when you're just working with integers,
+				# so I tried the following code to automatically convert integer string into integer
+				# when it's obvious. However, the performance drop is untolerable.
+				# Thus, commented out.
+				#
+				# if v && @cols_meta[i-1] == java.sql.Types::NUMERIC && v !~ /[\.e]/i
+				# 	v.to_i
+				# else
+				# 	v
+				# end
 				yield Connection::Row.new(
 						@col_labels,
-						(1..@num_col).map { | i |
-							v = @rset.send(GETTER_MAP.fetch(@cols_meta[i-1], :get_string), i)
+						@col_labels_d,
+						@getters.map { |gt|
+							v = @rset.send gt, idx+=1
 							@rset.was_null ? nil : v
 						},
 						count += 1)
@@ -52,48 +66,20 @@ private
 		@rsmd = @rset.get_meta_data
 		@num_col = @rsmd.get_column_count
 		@cols_meta = []
+		@getters = []
 		@col_labels = []
+		@col_labels_d = []
 		(1..@num_col).each do | i |
 			@cols_meta << @rsmd.get_column_type(i)
+			@getters << JDBCHelper::Connection::GETTER_MAP.fetch(@cols_meta.last, :get_string)
+
 			@col_labels << @rsmd.get_column_label(i)
+			@col_labels_d << @col_labels.last.downcase
+
 		end
 
 		@closed = false
 	end
-
-	GETTER_MAP =
-	{
-		java.sql.Types::TINYINT => :get_int,
-		java.sql.Types::SMALLINT => :get_int,
-		java.sql.Types::INTEGER => :get_int,
-		java.sql.Types::BIGINT => :get_long,
-
-		java.sql.Types::CHAR => :get_string,
-		java.sql.Types::VARCHAR => :get_string,
-		java.sql.Types::LONGVARCHAR => :get_string,
-		(java.sql.Types::NCHAR        rescue nil) => :get_string,
-		(java.sql.Types::NVARCHAR     rescue nil) => :get_string,
-		(java.sql.Types::LONGNVARCHAR rescue nil) => :get_blob, # FIXME: MySQL
-		java.sql.Types::BINARY => :get_string,
-		java.sql.Types::VARBINARY => :get_string,
-		java.sql.Types::LONGVARBINARY => :get_blob,	# FIXME: MySQL
-
-		java.sql.Types::REAL => :get_double,
-		java.sql.Types::FLOAT => :get_float,
-		java.sql.Types::DOUBLE => :get_double,
-		java.sql.Types::NUMERIC => :get_string, # FIXME
-		java.sql.Types::DECIMAL => :get_string, # FIXME
-
-		java.sql.Types::DATE => :get_date,
-		java.sql.Types::TIME => :get_time,
-		java.sql.Types::TIMESTAMP => :get_timestamp,
-
-		java.sql.Types::BLOB => :get_blob,
-		java.sql.Types::CLOB => :get_string,
-		(java.sql.Types::NCLOB rescue nil) => :get_string,
-
-		java.sql.Types::BOOLEAN => :get_boolean
-	} # :nodoc:
 end#ResultSetEnumerator
 end#Connection
 end#JDBCHelper

data/lib/jdbc-helper/connection/row.rb

@@ -105,9 +105,9 @@ class Row
 	alias :== :eql?
 
 private
-	def initialize(col_labels, values, rownum) # :nodoc:
+	def initialize(col_labels, col_labels_d, values, rownum) # :nodoc:
 		@labels = col_labels
-		@labels_d = col_labels.map { | l | l.downcase }
+		@labels_d = col_labels_d
 		@values = values
 		@rownum = rownum
 

data/lib/jdbc-helper/connection/type_map.rb

@@ -0,0 +1,72 @@
+# encoding: UTF-8
+# Junegunn Choi (junegunn.c@gmail.com)
+
+module JDBCHelper
+class Connection
+	RUBY_SQL_TYPE_MAP = {
+		Fixnum => java.sql.Types::INTEGER,
+		Bignum => java.sql.Types::BIGINT,
+		String => java.sql.Types::VARCHAR,
+		Float  => java.sql.Types::DOUBLE,
+		Time   => java.sql.Types::TIMESTAMP
+	}
+
+	SETTER_MAP =
+	{
+		'String' => :setString,
+		'Fixnum' => :setInt,
+		'Float' => :setDouble,
+		# See there's a caveat. Check out ParameterizedStatement#set_param
+		'Time' => :setTimestamp,
+
+		'Java::JavaSql::Date' => :setDate,
+		'Java::JavaSql::Time' => :setTime,
+		'Java::JavaSql::Timestamp' => :setTimestamp,
+		'Java::JavaSql::Blob' => :setBinaryStream,
+
+		#########
+		# MySQL #
+		#########
+		# Only available when MySQL JDBC driver is loaded.
+		# So we use the string representation of the class.
+		'Java::ComMysqlJdbc::Blob' => :setBinaryStream
+
+		# FIXME-MORE
+	} # :nodoc:
+
+	GETTER_MAP =
+	{
+		java.sql.Types::TINYINT => :getInt,
+		java.sql.Types::SMALLINT => :getInt,
+		java.sql.Types::INTEGER => :getInt,
+		java.sql.Types::BIGINT => :getLong,
+
+		java.sql.Types::CHAR => :getString,
+		java.sql.Types::VARCHAR => :getString,
+		java.sql.Types::LONGVARCHAR => :getString,
+		(java.sql.Types::NCHAR        rescue nil) => :getString,
+		(java.sql.Types::NVARCHAR     rescue nil) => :getString,
+		(java.sql.Types::LONGNVARCHAR rescue nil) => :getBlob, # FIXME: MySQL
+		java.sql.Types::BINARY => :getString,
+		java.sql.Types::VARBINARY => :getString,
+		java.sql.Types::LONGVARBINARY => :getBlob,	# FIXME: MySQL
+
+		java.sql.Types::REAL => :getDouble,
+		java.sql.Types::FLOAT => :getFloat,
+		java.sql.Types::DOUBLE => :getDouble,
+		java.sql.Types::NUMERIC => :getString, # FIXME: get_big_decimal=no inherent jruby support
+		java.sql.Types::DECIMAL => :getString, # FIXME: get_big_decimal
+
+		java.sql.Types::DATE => :getDate,
+		java.sql.Types::TIME => :getTime,
+		java.sql.Types::TIMESTAMP => :getTimestamp,
+
+		java.sql.Types::BLOB => :getBlob,
+		java.sql.Types::CLOB => :getString,
+		(java.sql.Types::NCLOB rescue nil) => :getString,
+
+		java.sql.Types::BOOLEAN => :getBoolean
+	} # :nodoc:
+end#Connection
+end#JDBCHelper
+