fireruby 0.1.0-powerpc-darwin → 0.2.0-powerpc-darwin

data/doc/README

@@ -1,39 +1,305 @@
-= FireRuby - Interface Library For The Firebird Database
+== FireRuby Version 0.2.0
+This is the second release of the FireRuby library. FireRuby is an extension to
+the Ruby language that provides access to the functionality of the Firebird
+relational database management system.
 
-This is the initial release of the FireRuby library. The FireRuby library
-provides an interface to the Firebird open source database management system.
-The library has been developed as an extension to the Ruby language using the
-Ruby interface API. The library is provided in binary form only to avoid
-compilation issues.
+Still no Linux build as I don't have a Linux box to build it on.
 
-If you are wondering why I haven't released a version of the library for Linux
-it is simply that I do not have access to a Linux box to build it. I hope to
-rectify this situation in the future but there is no definite timetable for
-doing this yet.
+== Enhancements & Alterations
 
-== Usage
+This release sees a switch away from returning arrays containing the row data
+for queries. Calling the fetch method on a ResultSet object returns an object
+of the new Row class. This class possesses a lot more information on the row
+data, including the column name, column aliases, row number and column data.
+See the API documentation for more information on this class.
 
-The library is provided as a gem. Installation follows the normal procedure for
-gem installation. The installation includes API documentation in HTML format.
-Some examples will be provided at a later date.
+A change has been made to the Database and Connection classes. Previously the
+database user name and password was specified when creating a Database object.
+This didn't make sense so the user name and password have now been switched to
+be parameters of the connect method. The Connection class has also be updated
+to reflect this change. Apologies if this breaks existing code but this kind of
+change is better done sooner rather than later.
+
+A few additional methods have been added to the existing class set. The
+ResultSet class now has a method call exhausted? that can be used to detect
+when there are no more rows available (the fetch method must have been called
+at least once however). The Statement object now has a parameter_count method
+that returns a count of the number of parameters require for the execution of
+the SQL statement.
+
+Also improved the documentation a little, by adding in the missing documentation
+for the Blob class, including a piece on the actual usage of the library in
+code, and adding a source example.
+
+== Bug Fixes
+
+A problem with using scalar numeric values as a parameter to an insert
+Statement was corrected and the whole area of input parameter type conversion
+tidied up a little.
 
 == Issues
 
 Nothing is perfect so this section outlines those issues that are known to
-exist before the release of the library.
-
- - The library currently does not support array columns. This may be implemented
-   for a later release depending on demand.
-   
- - There is an issue with storing and retrieving float values. The value is
-   stored but the actual value stored seems to be out by a small amount. This
-   will require further investigation.
-   
- - There is an issue with the use of anonymous transactions inside of a block
-   for the Database#connect method. An attempt is made to close the connection
-   when the block exits. If, within the block, there is a call to the
-   Connection#execute_immediate method that generates a result set and,
-   subsequently, an exception is raised the anonymous transaction used in the
-   execute_immediate will be unavailable for closure. This will, in turn,
-   make it impossible to close the connection, resulting in an exception. As
-   a work around, don't use anonynous transactions.
+exist as of this release.
+
+- The library currently does not support array columns. This may be implemented
+  for a later release depending on demand.
+  
+- There is an issue with the use of anonymous transactions inside of a block
+  for the Database#connect method. An attempt is made to close the connection
+  when the block exits. If, within the block, there is a call to the
+  Connection#execute_immediate method that generates a result set and,
+  subsequently, an exception is raised the anonymous transaction used in the
+  execute_immediate will be unavailable for closure. This will, in turn,
+  make it impossible to close the connection, resulting in an exception. As
+  a work around, don't use anonymous transactions for queries.
+
+== Installation & Usage
+
+The library is provided as a gem and built for use with Ruby 1.8+. Testing
+against an earlier release of Ruby has not been performed. Installation requires
+the Ruby Gems package to be installed. Assuming that these installation criteria
+have been met the library can be installed on Windows by executing a command
+such as the following...
+
+   gem install fireruby-0.2.0-mswin32.gem
+   
+On the Mac OS X platform you may require super user privilege if your Ruby is
+installed to the default location (i.e. /usr/local/lib). In this case you can
+use the sudo command to make the installation like this...
+
+   sudo gem install fireruby-0.2.0-powerpc-darwin.gem
+   
+Once the gem installation is complete the FireRuby functionality can be accessed
+in code with the usual gem style requires...
+
+   require 'rubygems'
+   require_gem 'fireruby'
+  
+== Build Details
+
+The FireRuby library is an extension of the Ruby language written in C. For Mac
+OS X the library was built against Firebird installed as a framework, version
+1.5.1, and with Ruby version 1.8.2. For the Windows platform the library was
+built against a Ruby installation created using the one-click installer, version
+1.8.2. The Windows build was created using the freely available Microsoft
+compilers and SDKs and built against a standard installation of Firebird,
+version 1.5.2. 
+  
+== So How Do I Use It?
+
+This section will provide some examples of usage for the the FireRuby classes.
+Throughout the code the following set of assumptions are made.
+
+- The user name and password that will be employed to attach to the database
+  are 'sysdba' and 'masterkey' respectively (the Firebird defaults).
+
+- The databases attached to will all be local (i.e. they will all reside on the
+  same machine) as the test code.
+  
+A database, from the Firebird perspective, is made up of one or more files. From
+a FireRuby perspective a user interaction with a database starts through the
+Database class. This class provides facilities that allow for creating, dropping
+and connecting to database instances. For example, to obtain a connection to a
+database you would use something like the following...
+
+   require 'rubygems'
+   require_gem 'fireruby'
+   
+   include FireRuby
+   
+   db = Database.new('./test.fdb')
+   c  = db.connect('sysdba', 'masterkey')
+   
+This example starts by requiring the necessary files and including the FireRuby
+module locally - later examples will not detail these lines but they are always
+required to use the FireRuby code.
+
+The first line of code after the include creates a new database object. This
+process does not actually create the database file (see the Database#create
+method API documentation if that is what you want to do), it simple creates an
+abstract reference to a database. In creating the Database object we had to
+provide a database specification string which identifies the database we want to
+access. In this case we are specifying a database in the current working
+directory called 'test.fdb'. See the Firebird documentation for details on the
+structure of more complex database specifications.
+
+The last line of code in the example given above opens a connection to the
+database. In doing this we had to provide two parameters, the database user
+name and password. These are required to gain access to the database.
+
+A connection represents a conduit to a database and obtaining a connection is a
+prerequisite to working with the database. The FireRuby library support having
+multiple connections, to one or more databases, using one or more users, active
+simultaneously. FireRuby represents a database connection through objects of the
+Connection class. This class provides functionality to determine the current
+state a database connection (open or closed) and for closing the connection.
+Connections take up resources, both locally and on the database server and
+should be explicitly closed when they are no longer required.
+
+The connection class also provides a set of conveniences methods to allow for
+the execution of SQL against a database. These methods, execute_immediate and
+execute, represently two slightly different approaches to executing SQL against
+the database. Refer to the API documentation for more information.
+
+An advantage of using a relational database management system like Firebird is
+that it provides transactions. A transaction represents a block of work that is
+either all completed successful or none of it is applied. From the perspective
+of the database this means that a series of steps that make changes to the
+tables in the database can be wrapped in a transaction to insure that they
+either all complete or that none of the changes are applied.
+
+The FireRuby library represents a database transaction through instances of the
+Transaction class. There are two ways of obtaining a Transaction using the
+library, both requiring you to have an open database connection. The first way
+is to construct a new Transaction object like so...
+
+   tx = Transaction.new(connection)
+   
+The Transaction constructor takes a single parameter which must be either a
+Connection object or an array of Connection objects. If you pass an array of
+Connection objects to this constructor then the Transaction created will apply
+across all of the databases that the connections refer to, allowing you to
+have transactional control of work that must utilise more than one database. The
+second way to obtain a transaction is to simply request one from a Connection
+object, like so.
+
+   tx = connection.start_transaction
+   
+In this case the transaction will only ever apply to one database, the one that
+the connection relates to. This method also accepts a block, taking a single
+parameter. The parameter passed to the block will be the transaction created.
+In this case the lifetime of the transaction is delimited by the block. If the
+block completes successfully then the work of the transaction will be committed
+to the database. If the block raises an exception then the transactional work
+will be rolled back.
+
+When the block of work associated with a transaction is complete the user must
+instruct the system to either apply the changes implemented by the work or to
+discard them. This can be done by calling the commit or rollback methods of the
+Transaction class respectively. Once a transaction has been committed or rolled
+back it can no longer be used and should be discarded. Note that attempts to
+close a connection that has an active transaction against it will fail, so one
+of the commit or rollback methods should be explictly called in code. The
+block technique detailed above helps protect against the failure to do this and
+is a useful technique.
+
+The Transaction object provides a number of other informational and utility
+methods. Check the API documentation for this class for more information.
+
+So we've looked at connections and transactions, but how do we actually do
+something practical with the database. Well there are a number of possible
+approaches that we can take to this. Both the Connection and Transaction classes
+have convenience method for the execution of SQL statements and these are useful
+for quick SQL. Where you want something that you can repeatedly reuse and,
+optionally, pass parameters to then you need the Statement class.
+
+The Statement class represents a SQL statement that has been validated and
+prepared for execution. Here's an example of creating a SQL statement...
+
+   s = Statement.new(cxn, tx, 'SELECT * FROM MY_TABLE', 3)
+   
+In this example we have created a Statement object that wraps a SQL select from
+a table called MY_TABLE. The first parameter to the constructor is a Connection
+object and the second is a Transaction, both mandatory. You may be thinking
+'why do I need a transaction here, I'm not changing anything?'. This is true
+(well sort of) but it's a requirement of the underlying database system. This
+is also the case for the final parameter to the constructor. The value 3 is
+the SQL dialect to be used with the Statement. This exists for reason arising
+from the move from closed source Interbase to open source Firebird. The
+parameter should be given a value of between 1 and 3. If you're not sure what
+this is and you're only using Firebird it's probably safe to use a value of
+3 here. Other values are for backward compatibility. Consult the Firebird and
+Interbase documentation for more details.
+
+Anyway, now that we have our Statement how do we use it. Well, there are two
+approaches to using the Statement object. For statements like the one used
+above, queries that take no parameters, you can use the Statement object to
+build a ResultSet object, like so...
+
+   r = ResultSet.new(s)
+   
+The ResultSet class will be covered in a little more detail below. The other
+means by which a Statement can be used is to call one of it's execute methods.
+The one to be called depends on whether the Statement requires parameters or
+not. What are parameters you ask? Well, look at the following...
+
+   s = Statement.new(cxn, tx, 'SELECT * FROM MY_TABLE WHERE MYID = ?', 3)
+   
+Note that the SQL select for this Statement contains a '?'. This is a position
+holder for a value that the statement expects to be provided later. A Statement
+that wraps such a piece of SQL must be provided with the necessary parameters
+to execute properly. Where a Statement object represents SQL that requires a
+parameter then the execute_for method must be called, like this...
+
+   r = s.execute_for([25])
+   
+This code executes the SQL substituting the parameters from the array of data
+passed to the function call. If a Statement object represents SQL that does not
+require parameter values a call to the execute method will suffice, such as the
+following...
+
+   r = s.execute
+   
+The execute methods for the Statement class, as with all of the execute methods
+for the FireRuby library, have two potential return values. They will either
+return nil or they will return a ResultSet object. A ResultSet object will only
+be returned for SQL statements that constitute a query, irrespective of whether
+that query returns any data. For all other SQL statements the various execute
+method will return nil.
+
+A ResultSet object represents a handle by which the data retrieved for a SQL
+query can be accessed. To fetch a row of data from a ResultSet object you call
+the fetch method, like the following...
+
+   row = r.fetch
+   
+This fetches a single row of data for a query represented as a Row object (which
+will be covered shortly). The ResultSet class also provides for iteration across
+the contents of a result set by providing an each method. The block to the each
+method will be passed the data for the ResultSet, a row at a time.
+
+It should be noted that both the Statement and ResultSet objects hold resources
+while they are active. They both possess close methods and these should be
+explicitly called to release the associated resources. The exception to this
+rule is for ResultSets. If you select all of the rows from a ResultSet then the
+resources for the ResultSet are automatically released. It is still safe to call
+close on such a ResultSet as this will not cause errors.
+
+Okay, so you've gotten a row of data in the form of a Row object from your
+ResultSet, how do we get the data out of it? Well, there are a number of ways
+of doing this. You can treat the Row object like an array and dereference the
+columns of data within the row like this...
+
+   value = row[1]
+   
+The index specified to the array dereference operator specifies the column that
+you want the data for. Column indices start at 0. Alternatively you can use the
+column name to access the data, like this...
+
+   value = row['MYID']
+   
+This is beneficial as it frees you from the constraint of knowing the ordering
+of the columns within the row. For more information of the Row class please
+consult the API documentation.
+
+Well that covers the bulk of the classes provided by the FireRuby library. The
+three which haven't been touched upon are the Generator class, the Blob class
+and the FireRubyException class.
+
+The Generator class is a wrapper around the Firebird generator facility. A
+generator, also known as a sequence, provides a means of creating a list of
+numeric values in a way that is guaranteed to be thread and process safe. Used
+properly generators can be employed to create unique sequences that make perfect
+table keys. Consult the API documentation for more details on the Generator
+class.
+
+The Blob class is returned as part of the Row object data obtained from a
+ResultSet. The class wraps the concept of a binary large object stored in the
+database. Consult the API documentation for further information.
+
+The FireRubyException class is the error class used by the FireRuby library
+whenever it hits trouble. If an exception is raised by the FireRuby code then
+its extremely likely that it will be an instance of this class. The class
+provides a means of finding out a little more about what exactly has gone
+wrong. Again, consult the API documentation for more details.

data/examples/example01.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require_gem 'fireruby'
+
+include FireRuby
+
+# SQL constants.
+CREATE_TABLE_SQL = 'CREATE TABLE TESTTABLE (TESTID INTEGER NOT NULL PRIMARY '\
+                   'KEY, TESTTEXT VARCHAR(100), TESTFLOAT NUMERIC(6,2), '\
+                   'CREATED TIMESTAMP)'
+DROP_TABLE_SQL   = 'DROP TABLE TESTTABLE'
+INSERT_SQL       = 'INSERT INTO TESTTABLE VALUES(?, ?, ?, ?)'
+SELECT_SQL       = 'SELECT * FROM TESTTABLE'
+
+begin
+   # Check if the database file exists.
+   db = nil
+   if File.exist?('./example.fdb') == false
+      # Create the database file.
+      db = Database.create('./example.fdb', 'sysdba', 'masterkey', 1024, 'ASCII')
+   else
+      # Create the databse object.
+      db = Database.new('./example.fdb')
+   end
+   
+   # Obtain a connection to the database.
+   db.connect('sysdba', 'masterkey') do |cxn|   
+      # Create the database table.
+      cxn.execute_immediate(CREATE_TABLE_SQL)
+      
+      # Insert 50 rows into the database.
+      decimal = 1.0
+      cxn.start_transaction do |tx|
+         s = Statement.new(cxn, tx, INSERT_SQL, 3)
+         1.upto(20) do |number|
+            s.execute_for([number, "Number is #{number}.", decimal, Time.new])
+            decimal = decimal + 0.24
+         end
+         s.close
+      end
+      
+      # Select back the rows inserted and display them
+      rows = cxn.execute_immediate(SELECT_SQL)
+      rows.each do |row|
+         puts "-----"
+         puts "Test Id:      #{row['TESTID']}"
+         puts "Test Text:    '#{row['TESTTEXT']}'"
+         puts "Test Float:   #{row['TESTFLOAT']}"
+         puts "Test Created: #{row['CREATED']}"
+         puts "-----"
+      end
+      rows.close
+      
+      # Drop the table.
+      cxn.execute_immediate(DROP_TABLE_SQL)
+   end
+rescue Excepton => error
+   puts error.message
+end

data/lib/mkdoc

@@ -1 +1 @@
-rdoc --op ../doc src.rb
+rdoc -m README src.rb README

data/lib/src.rb

@@ -13,7 +13,7 @@ module FireRuby
    #
    # This class provides the exception type used by the FireRuby library.
    #
-   class FireRubyError
+   class FireRubyException
       #
       # This is the constructor for the FireRubyError class.
       #
@@ -62,20 +62,10 @@ module FireRuby
       # This is the constructor for the Database class.
       #
       # ==== Parameters
-      # user::      A string containing the user name that will be used to
-      #             connect to the database.
-      # password::  A string containing the user password that will be used to
-      #             connect to the database.
       # file::      A string containing the database file specifier. This can
       #             include details for a remote server if needed.
       #
-      def initialize(user, password, file)
-      end
-      
-      #
-      # This is the accessor for the user database attribute.
-      #
-      def user
+      def initialize(file)
       end
       
       
@@ -93,11 +83,15 @@ module FireRuby
       # block completes. If a block is specified the connection is provided
       # as a parameter to the block.
       #
+      # ==== Parameters
+      # user::      The user name to be used in making the connection.
+      # password::  The password to be used in making the connection.
+      #
       # ==== Exceptions
       # Exception::  Thrown whenever a problem occurs connecting with the
       #              database.
       #
-      def connect
+      def connect(user, password)
          yield(connection)
       end
       
@@ -106,11 +100,15 @@ module FireRuby
       # This method attempts to drop the database referred to by the details
       # in a Database object.
       #
+      # ==== Parameters
+      # user::      The user name to be used in dropping the database.
+      # password::  The password to be used in dropping the database.
+      #
       # ==== Exceptions
       # FireRubyError::  Thrown whenever a problem occurs dropping the database
       #                  instance.
       #
-      def drop
+      def drop(user, password)
       end
       
       
@@ -148,13 +146,17 @@ module FireRuby
       #
       # ==== Parameters
       # database::  A reference to the Database object to be connected to.
+      # user::      A reference to the user name to be used in making the
+      #             database connection.
+      # password::  A reference to the user password to be used in making the
+      #             connection.
       #
       # ==== Exceptions
       # Exception::  Generated whenever an invalid database is specified to
       #              the method or an issue occurs establishing the database
       #              connection.
       #
-      def initialize(database)
+      def initialize(database, user, password)
       end
       
       
@@ -195,6 +197,14 @@ module FireRuby
       end
       
       
+      #
+      # This method retrieves the user name that was used in creating a
+      # Connection object.
+      #
+      def user
+      end
+      
+      
       #
       # This method generates a simple descriptive string for a Connection
       # object.
@@ -463,6 +473,15 @@ module FireRuby
       end
       
       
+      #
+      # This method fetches a count of the number of dynamic parameters for
+      # a statement object (i.e. the number of parameters that must be provided
+      # with values before the SQL statement can be executed).
+      #
+      def parameter_count
+      end
+      
+      
       #
       # This method executes the SQL statement within a Statement object. This
       # method returns a ResultSet object if the statement executed was a SQL
@@ -599,6 +618,24 @@ module FireRuby
       end
       
       
+      #
+      # This method is used to determine if all of the rows have been retrieved
+      # from a ResultSet object. This method will always return false until
+      # the fetch method has been called at least once so it cannot be used to
+      # detect a result set that returns no rows.
+      #
+      def exhausted?
+      end
+      
+      
+      #
+      # This method fetches a count of the total number of rows retrieved
+      # from a result set.
+      #
+      def row_count
+      end
+      
+      
       #
       # This method provides an iterator for the (remaining) rows contained in
       # a ResultSet object.
@@ -628,6 +665,112 @@ module FireRuby
    end
    
    
+   #
+   # This class models a row of data fetched as part of a SQL query.
+   #
+   class Row
+      #
+      # This is the constructor for the Row class. This method shouldn't really
+      # be used as Row objects are automatically created by ResultSets.
+      #
+      # ==== Parameters
+      # results::  The ResultSet object that the row relates to.
+      # data::     An array containing the row data values.
+      # number::   The row number for the new row.
+      #
+      def initialize(results, data, number)
+      end
+      
+      #
+      # This is the accessor for the row number attribute. This will generally
+      # reflect the order the row was fetched from the result set in, with 1
+      # being the first row retrieved.
+      #
+      def number
+      end
+      
+      
+      #
+      # This method fetches a count of the number of columns of data that are
+      # available from a row.
+      #
+      def column_count
+      end
+      
+      
+      #
+      # This method fetches the name of a column within a row of data.
+      #
+      # ==== Parameters
+      # index::  The index of the column to fetch the name for. The first
+      #          column in the row is at offset zero.
+      #
+      def column_name(index)
+      end
+      
+      
+      #
+      # This method fetches the alias of a column within a row of data.
+      #
+      # ==== Parameters
+      # index::  The index of the column to fetch the alias for. The first
+      #          column in the row is at offset zero.
+      #
+      def column_alias(index)
+      end
+      
+      
+      #
+      # This method fetches the value associated with a column within a Row
+      # object.
+      #
+      # ==== Parameters
+      # index::  Either the offset of the column to retrieve the value of or
+      #          the name of the column to retrieve the value of (column name
+      #          comparisons are case sensitive).
+      #
+      def [](index)
+      end
+   end
+   
+   #
+   # This class represents Blob data fetched from the database. The class defers
+   # the actual loading of the blob until requested. The class is somewhat basic
+   # and maybe expanded upon in later releases.
+   #
+   class Blob
+      #
+      # This is the constructor for the Blob class. This shouldn't really be
+      # used outside of the FireRuby library.
+      #
+      def initialize
+      end
+      
+      
+      #
+      # This method loads the entire data set for a blob as a string.
+      #
+      def to_s
+      end
+      
+      
+      #
+      # This method closes a blob, freeing any resources associated with it.
+      #
+      def close
+      end
+      
+      
+      #
+      # This method loads the segments of a blob one after another. The blob
+      # segments are passed as strings to the block passed to the method.
+      #
+      def each
+         yield segment
+      end
+   end
+   
+   
    #
    # This class represents a Firebird generator entity.
    #