jdbc-helper 0.1.3 → 0.2.0

data/README.rdoc

@@ -4,7 +4,7 @@ A JDBC helper for Ruby/Database developers.
 JDBCHelper::Connection object wraps around a JDBC connection and provides much nicer interface to
 crucial database operations from primitive selects and updates to more complex ones involving
 batch updates, prepared statements and transactions.
-As the name implies, only works on JRuby.
+As the name implies, this gem only works on JRuby.
 
 = Examples
 
@@ -108,6 +108,22 @@ 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)
+  # 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|
+    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!
+
 == Contributing to jdbc-helper
  
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet

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

@@ -2,18 +2,18 @@
 # Junegunn Choi (junegunn.c@gmail.com)
 
 module JDBCHelper
+class Connection
 # An encapsulation of Java PreparedStatment object.
 # Used to execute parameterized queries efficiently.
-# Has a very similar set of interface as JDBCHelper::Connection.
-#
-# e.g.
+# Has a very similar set of interface to that of JDBCHelper::Connection.
 #
+# @example
 #   pstmt = conn.prepare("SELECT * FROM T WHERE a = ? and b = ?")
 #   rows = pstmt.query(10, 20)
 #   enum = pstmt.enumerate(10, 20)
-#
-class Connection
 class PreparedStatement
+	# SQL string
+	# @return [String]
 	attr_reader :sql
 
 	# Returns the encapsulated JDBC PreparedStatement object.
@@ -22,50 +22,58 @@ class PreparedStatement
 	end
 
 	# Returns the number of parameters required
+	# @return [Fixnum]
 	def parameter_count
 		@pmd ||= @pstmt.get_parameter_meta_data
 		@pmd.get_parameter_count
 	end
 
+	# @return [Fixnum]
 	def update(*params)
 		check_closed
 
 		set_params(params)
-		measure(:p_update) { @pstmt.execute_update }
+		measure_exec(:p_update) { @pstmt.execute_update }
 	end
 
+	# @return [Array] Returns an Array if block is not given
 	def query(*params, &blk)
 		check_closed
 
 		set_params(params)
 		# sorry, ignoring privacy
 		@conn.send(:process_and_close_rset,
-				   measure(:p_query) { @pstmt.execute_query }, &blk)
+				   measure_exec(:p_query) { @pstmt.execute_query }, &blk)
 	end
 
+	# @return [JDBCHelper::Connection::ResultSetEnumerator]
 	def enumerate(*params, &blk)
 		check_closed
 
 		return query(*params, &blk) if block_given?
 
 		set_params(params)
-		ResultSetEnumerator.new(measure(:p_query) { @pstmt.execute_query })
+		ResultSetEnumerator.new(measure_exec(:p_query) { @pstmt.execute_query })
 	end
 
-	# batch interface
+	# Adds to the batch
+	# @return [NilClass]
 	def add_batch(*params)
 		check_closed
 
 		set_params(params)
 		@pstmt.add_batch
 	end
+	# Executes the batch
 	def execute_batch
 		check_closed
 
-		measure(:p_execute_batch) {
+		measure_exec(:p_execute_batch) {
 			@pstmt.executeBatch
 		}
 	end
+	# Clears the batch
+	# @return [NilClass]
 	def clear_batch
 		check_closed
 
@@ -74,12 +82,15 @@ class PreparedStatement
 
 	# Gives the JDBC driver a hint of the number of rows to fetch from the database by a single interaction.
 	# This is only a hint. It may no effect at all.
+	# @return [NilClass]
 	def set_fetch_size(fsz)
 		check_closed
 
 		@pstmt.set_fetch_size fsz
 	end
 
+	# Closes the prepared statement
+	# @return [NilClass]
 	def close
 		return if closed?
 		@pstmt.close
@@ -87,6 +98,7 @@ class PreparedStatement
 		@pstmt = @pstmts = nil
 	end
 
+	# @return [Boolean]
 	def closed?
 		@pstmt.nil?
 	end
@@ -117,8 +129,8 @@ private
 		end
 	end
 
-	def measure(type, &blk)	# :nodoc:
-		@conn.send(:measure, type, &blk)
+	def measure_exec(type, &blk)	# :nodoc:
+		@conn.send(:measure_exec, type, &blk)
 	end
 
 	def check_closed
@@ -127,10 +139,10 @@ private
 
 	SETTER_MAP =
 	{
- 		'Java::JavaSql::Date' => :setDate,
- 		'Java::JavaSql::Time' => :setTime,
- 		'Java::JavaSql::Timestamp' => :setTimestamp,
- 		'Time'                     => :setTimestamp,
+		'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.

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

@@ -2,12 +2,12 @@
 # Junegunn Choi (junegunn.c@gmail.com)
 
 module JDBCHelper
+class Connection
 # The result of database queries.
 # Designed to be very flexible on its interface.
 # You can access it like an array, a hash or an ORM object.
 #
-# e.g.
-#
+# @example
 #   conn.query('SELECT a, b, c FROM t') do | row |
 #       puts row.a
 #       puts row[1]
@@ -22,26 +22,36 @@ module JDBCHelper
 #
 #       puts row.rownum
 #   end
-#
-class Connection
 class Row
-	attr_reader :labels, :values, :rownum
+	# @return [Array] Labels of the columns
+	attr_reader :labels
+	# @return [Array] Values in Array
+	attr_reader :values
+	# @return [Fixnum] Sequential row number assigned within the scope of the query
+	attr_reader :rownum
 	alias_method :keys, :labels
 
 	include Enumerable
 
+	# @param [Fixnum/String] idx
+	# @return [Object]
 	def [](idx)
-		if idx.is_a? Fixnum
+		case idx
+		when Fixnum
 			raise RangeError.new("Index out of bound") if idx >= @values.length
 			@values[idx]
-		else
+		when String
 			# case-insensitive, assuming no duplicate labels
 			vidx = @labels_d.index(idx.downcase) or
 				raise NameError.new("Unknown column label: #{idx}")
 			@values[vidx]
+		else
+			# See how it goes...
+			@values[idx]
 		end
 	end
 
+	# @yield [Object]
 	def each(&blk)
 		@values.each { | v | yield v }
 
@@ -50,6 +60,7 @@ class Row
 		# end
 	end
 
+	# @return [String]
 	def inspect
 		strs = []
 		@labels.each do | col |
@@ -58,18 +69,22 @@ class Row
 		'[' + strs.join(', ') + ']'
 	end
 
+	# @return [String]
 	def to_s
 		@values.to_s
 	end
 
+	# @return [Array]
 	def to_a
 		@values
 	end
 
+	# @return [String]
 	def join(sep = $,)
 		to_a.join(sep)
 	end
 
+	# @return [Boolean]
 	def eql?(other)
 		self.hash == other.hash
 	end
@@ -86,15 +101,28 @@ private
 		@labels_d = col_labels.map { | l | l.downcase }
 		@values = values
 		@rownum = rownum
+
+		# @labels_d.each do | l |
+		# 	(class << self; self; end).instance_eval do
+		# 		define_method l do
+		# 			self[l]
+		# 		end
+		# 	end
+		# end
 	end
 
+	# Performs better than defining methods
 	def method_missing(symb, *args)
 		if vidx = @labels_d.index(symb.to_s.downcase)
-			@values[vidx]
+			begin
+				@values[vidx]
+			rescue NameError
+				raise NoMethodError.new("undefined method or attribute `#{symb}'")
+			end
 		elsif @values.respond_to?(symb)
 			@values.send(symb, *args)
 		else
-			raise NameError.new("Unknown method: #{symb}")
+			raise NoMethodError.new("undefined method or attribute `#{symb}'")
 		end
 	end
 

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

@@ -2,10 +2,11 @@
 # Junegunn Choi (junegunn.c@gmail.com)
 
 module JDBCHelper
-# Internal implementation for supporting query nesting.
-# Not thread-safe. Well, sharing a JDBC connection between threads is not the best idea anyway.
 class Connection
-class StatementPool # :nodoc:
+# Internal implementation for supporting query nesting.
+# Not thread-safe. (Sharing a JDBC connection between threads is not the best idea anyway.)
+# @private
+class StatementPool
 	def initialize(conn, max_size = 20)
 		@conn = conn
 		@max_size = max_size # TODO

data/lib/jdbc-helper/connection.rb

@@ -10,15 +10,12 @@ module JDBCHelper
 # Encapsulates JDBC database connection.
 # Lets you easily execute SQL statements and access their results.
 #
-#
-# = Examples
-# 
-# == Prerequisites
-# Add JDBC driver of the DBMS you're willing to use to your CLASSPATH
+# @example 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
+# @example Connecting to a database
 # 
 #  # :driver and :url must be given
 #  conn = JDBCHelper::Connection.new(
@@ -40,7 +37,7 @@ module JDBCHelper
 #  conn = JDBCHelper::MySQLConnector.connect('localhost', 'mysql', '', 'test')
 #  conn.close
 #	
-# == Querying database table
+# @example Querying database table
 #
 #  conn.query("SELECT a, b, c FROM T") do | row |
 #      p row.labels
@@ -61,10 +58,10 @@ module JDBCHelper
 #          # ...
 #      end
 #  end
-# == Updating database table
+# @example Updating database table
 #  del_count = conn.update("DELETE FROM T")
 # 
-# == Transaction
+# @example Transaction
 #  committed = conn.transaction do | tx |
 #      # ...
 #      # Transaction logic here
@@ -77,13 +74,13 @@ module JDBCHelper
 #      end
 #  end
 # 
-# == Using batch interface
+# @example Using batch interface
 #  conn.add_batch("DELETE FROM T");
 #  conn.execute_batch
 #  conn.add_batch("DELETE FROM T");
 #  conn.clear_batch
 #   
-# == Using prepared statements
+# @example Using prepared statements
 #  p_sel = conn.prepare("SELECT * FROM T WHERE b = ? and c = ?")
 #  p_sel.query(100, 200) do | row |
 #      p row
@@ -102,14 +99,14 @@ module JDBCHelper
 #  p_upd.execute_batch
 #  p_upd.close
 class Connection
-	Stat = Struct.new("DBExecStat", :type, :elapsed, :success_count, :fail_count) # :nodoc:
-
 	# 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
 
 	# Returns the underlying JDBC Connection object.
@@ -126,6 +123,7 @@ class Connection
 	#
 	# Must be closed explicitly if not used.
 	# If a block is given, the connection is automatically closed after executing the block.
+	# @param [Hash] args
 	def initialize(args = {})
 		# String-tolerance..
 		%w[driver url user password timeout].each do | strk |
@@ -168,13 +166,14 @@ class Connection
 	end
 
 	# Creates a prepared statement, which is also an encapsulation of Java PreparedStatement object
+	# @param [String] qstr SQL string
 	def prepare(qstr)
 		check_closed
 
 		return @pstmts[qstr] if @pstmts.has_key? qstr
 
 		pstmt =	PreparedStatement.send(:new, self, @pstmts, qstr,
-									  measure(:prepare) { @conn.prepare_statement(qstr) })
+									  measure_exec(:prepare) { @conn.prepare_statement(qstr) })
 		@pstmts[qstr] = pstmt
 		pstmt
 	end
@@ -182,6 +181,8 @@ class Connection
 	# Executes the given code block as a transaction. Returns true if the transaction is committed.
 	# A transaction object is passed to the block, which only has commit and rollback methods.
 	# The execution breaks out of the code block when either of the methods is called.
+	# @yield [JDBCHelper::Connection::Transaction] Responds to commit and rollback.
+	# @return [Boolean] True if committed
 	def transaction
 		check_closed
 
@@ -206,11 +207,13 @@ class Connection
 	end
 
 	# Executes an update and returns the count of the updated rows.
+	# @param [String] qstr SQL string
+	# @return [Fixnum] Count of affected records
 	def update(qstr)
 		check_closed
 
 		@spool.with do | stmt |
-			ret = measure(:update) { stmt.execute_update(qstr) }
+			ret = measure_exec(:update) { stmt.execute_update(qstr) }
 		end
 	end
 
@@ -227,11 +230,14 @@ class Connection
 	#           # ... and so on ...
 	#       end
 	#   end
+	# @param [String] qstr SQL string
+	# @yield [JDBCHelper::Connection::Row]
+	# @return [Array]
 	def query(qstr, &blk)
 		check_closed
 
 		@spool.with do | stmt |
-			measure(:query) { stmt.execute(qstr) }
+			measure_exec(:query) { stmt.execute(qstr) }
 			process_and_close_rset(stmt.get_result_set, &blk)
 		end
 	end
@@ -247,6 +253,9 @@ class Connection
 	#       puts
 	#   end
 	#
+	# @param [String] qstr SQL string
+	# @yield [JDBCHelper::Connection::Row] Yields each record if block is given
+	# @return [JDBCHelper::Connection::ResultSetEnumerator] Returns an enumerator if block is not given
 	def enumerate(qstr, &blk)
 		check_closed
 
@@ -254,7 +263,7 @@ class Connection
 
 		stmt = @spool.take
 		begin
-			measure(:query) { stmt.execute(qstr) }
+			measure_exec(:query) { stmt.execute(qstr) }
 		rescue Exception
 			@spool.give stmt
 			raise
@@ -264,6 +273,9 @@ class Connection
 	end
 
 	# Adds a statement to be executed in batch
+	# Adds to the batch
+	# @param [String] qstr
+	# @return [NilClass]
 	def add_batch(qstr)
 		check_closed
 
@@ -272,17 +284,19 @@ class Connection
 	end
 
 	# Executes batched statements. No effect when no statment is added
+	# @return [NilClass]
 	def execute_batch
 		check_closed
 
 		return unless @bstmt
-		ret = measure(:execute_batch) { @bstmt.execute_batch }
+		ret = measure_exec(:execute_batch) { @bstmt.execute_batch }
 		@spool.give @bstmt
 		@bstmt = nil
 		ret
 	end
 
 	# Clears the batched statements
+	# @return [NilClass]
 	def clear_batch
 		check_closed
 
@@ -294,6 +308,8 @@ class Connection
 
 	# Gives the JDBC driver a hint of the number of rows to fetch from the database by a single interaction.
 	# This is only a hint. It may have no effect at all.
+	# @param [Fixnum] fsz
+	# @return [NilClass]
 	def set_fetch_size(fsz)
 		check_closed
 
@@ -302,6 +318,7 @@ class Connection
 	end
 
 	# Closes the connection
+	# @return [NilClass]
 	def close
 		return if closed?
 		@pstmts.each { | q, pstmt | pstmt.close }
@@ -311,19 +328,40 @@ class Connection
 	end
 
 	# Returns if this connection is closed or not
+	# @return [Boolean]
 	def closed?
 		@conn.nil?
 	end
 
+	# @param [String] table_name Name of the table to be wrapped
+	# @return [JDBCHelper::TableWrapper]
+	def table table_name
+		JDBCHelper::TableWrapper.new self, table_name
+	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
 		# Commits the transaction
+		# @raise [JDBCHelper::Transaction::Commit]
 		def commit
 			@conn.commit
 			raise Commit
 		end
 		# Rolls back this transaction
+		# @raise [JDBCHelper::Transaction::Rollback]
 		def rollback
 			@conn.rollback
 			raise Rollback
@@ -374,7 +412,7 @@ private
 		accum.fail_count += fail_count
 	end
 
-	def measure(type)
+	def measure_exec(type)
 		begin
 			st = Time.now
 			ret = yield

data/lib/jdbc-helper/connector/mysql_connector.rb

@@ -7,6 +7,13 @@ class MySQLConnector
 	include Constants
 	include Constants::Connector
 
+	# @param [String] host
+	# @param [String] user
+	# @param [String] password
+	# @param [String] db
+	# @param [Fixnum] timeout
+	# @param [Hash] extra_params
+	# @return [JDBCHelper::Connection]
 	def self.connect(host, user, password, db,
 					 timeout = DEFAULT_LOGIN_TIMEOUT, 
 					 extra_params = DEFAULT_PARAMETERS[:mysql])

data/lib/jdbc-helper/connector/oracle_connector.rb

@@ -7,6 +7,12 @@ module OracleConnector
 	include Constants
 	include Constants::Connector
 
+	# @param [String] host
+	# @param [String] user
+	# @param [String] password
+	# @param [String] service_name
+	# @param [Fixnum] timeout
+	# @return [JDBCHelper::Connection]
 	def self.connect(host, user, password, service_name, timeout = DEFAULT_LOGIN_TIMEOUT)
 		Connection.new(
 			:driver   => JDBC_DRIVER[:oracle],
@@ -16,6 +22,12 @@ module OracleConnector
 			:timeout  => timeout)
 	end
 
+	# @param [String] host
+	# @param [String] user
+	# @param [String] password
+	# @param [String] sid
+	# @param [Fixnum] timeout
+	# @return [JDBCHelper::Connection]
 	def self.connect_by_sid(host, user, password, sid, timeout = DEFAULT_LOGIN_TIMEOUT)
 		Connection.new(
 			:driver   => JDBC_DRIVER[:oracle],