jdbc-wrapper 0.2 → 0.3

data/README

@@ -1,13 +1,29 @@
-Minimum Requirements
-====================
+= JDBC Wrapper (for JRuby)
+
+== Minimum Requirements
 
 * Java 1.5
 * JRuby 1.1 (tested with RC2)
 * JDBC Drivers
 
-How to Install
-==============
+== How to Install
 
 * gem install jdbc-wrapper
 * get your jdbc driver jars on your classpath
   (the easier way to do this is drop them in $JRUBY_HOME/lib)
+
+== How to Use
+
+  require 'rubygems'
+  require 'jdbc'
+
+  JDBC::DB.start(:h2,nil,nil,nil,nil,'foo') do |db|
+    db.query("CREATE TABLE records (name VARCHAR(80))")
+
+    db.query("INSERT INTO records (name) VALUES ('foo')")
+
+    db.query("SELECT * FROM records").each_hash do |row|
+      row.each { |key, value| puts "#{key} = #{value}" }
+    end
+  end
+

data/Rakefile

@@ -4,20 +4,29 @@ task :test do
   Rake.run_tests 'test/test_*.rb'
 end
 
+require 'rake/rdoctask'
+
+Rake::RDocTask.new do |rd|
+  rd.main = "README"
+  rd.rdoc_files.include("README", "lib/**/*.rb")
+end
+
 require 'rubygems' 
 Gem::manage_gems 
 require 'rake/gempackagetask' 
 
 gemspec = Gem::Specification.new do |s| 
   s.name = "jdbc-wrapper"
-  s.version = "0.2" 
+  s.version = "0.3" 
   s.author = "Larry Myers" 
-  s.email = "larry@larrymyers.com" 
+  s.email = "larry@larrymyers.com"
+  s.homepage = "http://jdbc-wrapper.rubyforge.org/"
+  s.rubyforge_project = "JDBC Wrapper"
   s.platform = Gem::Platform::RUBY 
   s.summary = "A basic JDBC wrapper for JRuby" 
   s.files = FileList["{examples,lib,test}/**/*","Rakefile","README"].to_a 
   s.require_path = "lib" 
-  s.has_rdoc = false 
+  s.has_rdoc = true 
 end 
 
 Rake::GemPackageTask.new(gemspec) do |pkg| 

data/lib/jdbc.rb

@@ -2,6 +2,9 @@ $:.unshift File.join(File.dirname(__FILE__),'.')
 
 require 'java'
 
+# Wraps the java.sql package in 
+# a module and makes it available
+# to the JDBC module.
 module JavaSql
   include_package 'java.sql'
 end

data/lib/jdbc/adapters.rb

@@ -5,3 +5,7 @@ require 'adapters/h2'
 require 'adapters/hsqldb'
 require 'adapters/mysql'
 require 'adapters/postgresql'
+
+# A set of wrapper classes to encapsulate each database engine. Each adapter
+# requires the standard connection parameters on instantiation. Two methods
+# are expected to exist on each adapter: class_name and connection_string.

data/lib/jdbc/db.rb

@@ -7,7 +7,15 @@ require 'fileutils'
 require 'adapters'
 
 module JDBC
+  # A database connection. The starting point for all interaction with the
+  # database. The JDBC drivers are not provided, so you are responsible for
+  # making sure the jar file is in the classpath so that JRuby will be able
+  # class load it.
   class DB
+    # Creates a new database connection, you are responsible for
+    # making sure the connection gets closed. The database engine
+    # param should be a symbol. Supported: :h2, :hsqldb, :derby
+    # :mysql, :postgresql
     def initialize(engine, host, port, user, password, schema)
       adapter = get_adapter(engine, host, port, user, password, schema)
       
@@ -21,11 +29,13 @@ module JDBC
       end
     end
     
-    def self.start(db_class, host, port, user, password, database)
+    # Takes a block, and provides an open database connection to the
+    # block. Will safely close the connection automatically.
+    def self.start(engine, host, port, user, password, database)
       db = nil
       
       begin
-          db = DB.new(db_class, host, port, user, password, database)
+          db = DB.new(engine, host, port, user, password, database)
       
           yield(db)
       rescue JavaSql::SQLException => e
@@ -35,6 +45,8 @@ module JDBC
       end
     end
   
+    # Takes a valid SQL string. Will return a Result object for a query,
+    # or the number of rows affected for an update.
     def query(sql)
       stmt = nil
       result = nil
@@ -55,10 +67,25 @@ module JDBC
       end
     end
     
+    # Takes a valid SQL string. Returns a PreparedStatement object if
+    # no block is given (you are required to close it). If a block is 
+    # provided it will pass the statement to the block, and it will 
+    # automatically close upon block exit.
     def prepare(sql)
-      return PreparedStatement.new(@conn.prepareStatement(sql))
+      stmt = PreparedStatement.new(@conn.prepareStatement(sql))
+      
+      if block_given?
+        yield(stmt)
+        
+        stmt.close
+        
+        return
+      end
+      
+      return stmt
     end
     
+    # Closes the database connection.
     def close
       @conn.close unless @conn.nil?
     end

data/lib/jdbc/prepared_statement.rb

@@ -1,10 +1,16 @@
 module JDBC
+  # Wraps a java PreparedStatement. 
   class PreparedStatement
+    # Takes a java PreparedStatement. You should not have to call this. It
+    # will be instantiated by a DB connection.
     def initialize(stmt)
       @stmt = stmt
       @meta_data = stmt.getParameterMetaData
     end
     
+    # Executes the statement with the provided list of comma separated
+    # arguments. Will return a Result for queries and the number of rows
+    # affected for updates.
     def execute(*args)
       if args.length != @meta_data.getParameterCount
         raise RuntimeError.new("Got #{args.length} params, " + 
@@ -24,6 +30,7 @@ module JDBC
       return @stmt.getUpdateCount
     end
     
+    # Closes the statement.
     def close
       @stmt.close
     end

data/lib/jdbc/result.rb

@@ -1,11 +1,20 @@
 module JDBC
+  # Result wraps a java ResultSet, and provides methods to both fetch rows
+  # one at a time, as well as ruby iterators. All rows are automatically
+  # converted to a ruby Array or Hash when they are fetched. Each column is
+  # casted to the equivalent ruby object if possible, otherwise it will be a
+  # String.
   class Result
+    # Takes a java ResultSet and Statement. You should not have to call this.
+    # A Result will usually be instantiated by a DB or PreparedStatement.
     def initialize(resultSet, statement)
       @rs = resultSet
       @stmt = statement
       @columns = get_rs_meta_data
     end
     
+    # Fetches the next row and returns it as an Array. Returns nil if no more
+    # rows are available and closes the Result.
     def fetch
       if @rs.next
         result = []
@@ -22,6 +31,13 @@ module JDBC
       return nil
     end
     
+    # Fetches the next row and returns it as a Hash. The column names are
+    # the keys. Returns nil is no more rows are available and closes the Result.
+    #
+    # Note: All column names are automatically lowercased for consistency
+    # since databases differ in behavior on this aspect. (ex: Derby is
+    # uppercase, Postgres is lowercase, and Mysql depends on how the table
+    # was created.)
     def fetch_hash
       if @rs.next
         result = {}
@@ -38,18 +54,23 @@ module JDBC
       return nil
     end
     
+    # Returns each row as an Array to the provided block. Will automatically
+    # close the Result after the block exits.
     def each
       while(result = fetch)
         yield(result)
       end
     end
   
+    # Returns each row as an Hash to the provided block. The column names 
+    # are the keys. Will automatically close the Result after the block exits.
     def each_hash
       while(result = fetch_hash)
         yield(result)
       end
     end
   
+    # Closes the Result
     def close
       @rs.close unless @rs.nil?
       @stmt.close unless @stmt.nil?

data/test/test_prepared_statement.rb

@@ -25,6 +25,8 @@ class TestDB < Test::Unit::TestCase
     
     assert_equal('bar', row[0])
     assert_equal(2, row[1])
+    
+    stmt.close
   end
   
   def test_runtime_error_on_invalid_arg_count
@@ -38,6 +40,8 @@ class TestDB < Test::Unit::TestCase
     rescue RuntimeError => e
       assert_equal("Got 2 params, expected 1.", e.message)
     end
+    
+    stmt.close
   end
   
   def create_and_populate_records_table

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 extensions: []
-homepage: 
+homepage: http://jdbc-wrapper.rubyforge.org/
 executables: []
 version: !ruby/object:Gem::Version
-  version: !str 0.2
+  version: !str 0.3
 post_install_message: 
-date: 2008-03-13 04:00:00 +00:00
+date: 2008-03-18 04:00:00 +00:00
 files: 
 - examples/derby.rb
 - examples/h2.rb
@@ -31,7 +31,7 @@ rdoc_options: []
 signing_key: 
 cert_chain: []
 name: jdbc-wrapper
-has_rdoc: false
+has_rdoc: true
 platform: ruby
 summary: A basic JDBC wrapper for JRuby
 default_executable: 
@@ -59,5 +59,5 @@ authors:
 - Larry Myers
 extra_rdoc_files: []
 requirements: []
-rubyforge_project: 
+rubyforge_project: JDBC Wrapper
 autorequire: