iotaz 0.1.0

data/examples/example01.rb

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby
+#
+#--
+# Copyright (C) Peter Wood, 2005
+#     
+# The contents of this file are subject to the Mozilla Public License Version
+# 1.1 (the "License"); you may not use this file except in compliance with the
+# License. You may obtain a copy of the License at 
+#
+# http://www.mozilla.org/MPL/
+#
+# Software distributed under the License is distributed on an "AS IS" basis,
+# WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
+# the specificlanguage governing rights and  limitations under the License.
+#
+# The Original Code is the FireRuby extension for the Ruby language.
+#
+# The Initial Developer of the Original Code is Peter Wood. All Rights
+# Reserved.     
+#++
+#
+
+require 'rubygems'
+require_gem 'iotaz'
+require_gem 'fireruby'
+
+include FireRuby
+include Iotaz
+
+TABLE_SQL     = 'create table account (id integer not null primary key,'\
+                'number varchar(10) not null, customer varchar(30), '\
+                'created timestamp not null, updated timestamp)'
+DB_FILE       = './accounts.fdb'
+DB_USER_NAME  = 'sysdba'
+DB_PASSWORD   = 'masterkey'
+CONFIGURATION = {'iotaz.database'          => 'firebird',
+                 'iotaz.firebird.user'     => DB_USER_NAME,
+                 'iotaz.firebird.password' => DB_PASSWORD,
+                 'iotaz.firebird.database' => DB_FILE}
+
+# The definition for the persistable class.
+class Account
+   attr_accessor :id, :number, :customer, :created, :updated
+   
+   def initialize(number, customer)
+      @number   = number
+      @customer = customer
+   end
+   
+   def to_s
+      "Id: #{@id}\nNumber: #{@number}\nCustomer: #{@customer}\n"\
+      "Created: #{@created}\nUpdated: #{@updated}"
+   end
+ 
+   def Account.iotaz_meta_data
+      IotazMetaData.scan(Account)
+   end
+ 
+   private :id=, :created=, :updated=
+end
+
+def create(session)
+   account = Account.new('ACC/001', 'Test Customer')
+   session.save(account)
+   puts "Save->\n#{account}"
+   account.id
+end
+
+def update(id, session)
+   account = session.load(Account, id)
+   account.customer = 'Updated Customer'
+   session.save(account)
+   puts "Update->\n#{account}"
+end
+
+def delete(id, session)
+   account = session.load(Account, id)
+   session.delete(account)
+   puts "Account record deleted."
+end
+
+begin
+   # Check if the database exists.
+   database = nil
+   if File.exist?(DB_FILE) == false
+      database = Database.create(DB_FILE, DB_USER_NAME, DB_PASSWORD, 1024, nil)
+      database.connect(DB_USER_NAME, DB_PASSWORD) do |connection|
+         connection.execute_immediate(TABLE_SQL)
+         Generator.create('ACCOUNT_ID_SQ', connection)
+      end
+   end
+   
+   factory = SessionFactory.new(CONFIGURATION)
+   session = factory.start
+   
+   id = create(session)
+   update(id, session)
+   delete(id, session)
+   
+   session.terminate
+   
+rescue Exception => error
+   puts error.message
+   error.backtrace.each {|step| puts "   #{step}"}
+end

data/examples/example02.rb

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby
+#
+#--
+# Copyright (C) Peter Wood, 2005
+#     
+# The contents of this file are subject to the Mozilla Public License Version
+# 1.1 (the "License"); you may not use this file except in compliance with the
+# License. You may obtain a copy of the License at 
+#
+# http://www.mozilla.org/MPL/
+#
+# Software distributed under the License is distributed on an "AS IS" basis,
+# WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
+# the specificlanguage governing rights and  limitations under the License.
+#
+# The Original Code is the FireRuby extension for the Ruby language.
+#
+# The Initial Developer of the Original Code is Peter Wood. All Rights
+# Reserved.     
+#++
+#
+
+require 'rubygems'
+require_gem 'iotaz'
+require_gem 'fireruby'
+
+include FireRuby
+include Iotaz
+
+TABLE_SQL     = 'create table account (id integer not null primary key,'\
+                'number varchar(10) not null, customer varchar(30), '\
+                'created timestamp not null, updated timestamp)'
+DB_FILE       = './accounts.fdb'
+DB_USER_NAME  = 'sysdba'
+DB_PASSWORD   = 'masterkey'
+CONFIGURATION = {'iotaz.database'          => 'firebird',
+                 'iotaz.firebird.user'     => DB_USER_NAME,
+                 'iotaz.firebird.password' => DB_PASSWORD,
+                 'iotaz.firebird.database' => DB_FILE}
+
+# The definition for the persistable class.
+class Account
+   include Persistent
+
+   sequence_attr   :id
+   persistent_attr :number
+   persistent_attr :customer
+   timestamp_attr  :created
+   timestamp_attr  :updated, nil, false, true
+  
+   def initialize(number, customer)
+      @number   = number
+      @customer = customer
+   end
+  
+   def to_s
+      "Id: #{@id}\nNumber: #{@number}\nCustomer: #{@customer}\n"\
+      "Created: #{@created}\nUpdated: #{@updated}"
+   end
+end
+
+def create(session)
+   account = Account.new('ACC/001', 'Test Customer')
+   session.save(account)
+   puts "Save->\n#{account}"
+   account.id
+end
+
+def update(id, session)
+   account = session.load(Account, id)
+   account.customer = 'Updated Customer'
+   session.save(account)
+   puts "Update->\n#{account}"
+end
+
+def delete(id, session)
+   account = session.load(Account, id)
+   session.delete(account)
+   puts "Account record deleted."
+end
+
+begin
+   # Check if the database exists.
+   database = nil
+   if File.exist?(DB_FILE) == false
+      database = Database.create(DB_FILE, DB_USER_NAME, DB_PASSWORD, 1024, nil)
+      database.connect(DB_USER_NAME, DB_PASSWORD) do |connection|
+         connection.execute_immediate(TABLE_SQL)
+         Generator.create('ACCOUNT_ID_SQ', connection)
+      end
+   end
+   
+   factory = SessionFactory.new(CONFIGURATION)
+   session = factory.start
+   
+   id = create(session)
+   update(id, session)
+   delete(id, session)
+   
+   session.terminate
+   
+rescue Exception => error
+   puts error.message
+   error.backtrace.each {|step| puts "   #{step}"}
+end

data/lib/iotaz.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+#
+#--
+# Copyright � Peter Wood, 2005
+# 
+# The contents of this file are subject to the Mozilla Public License Version
+# 1.1 (the "License"); you may not use this file except in compliance with the
+# License. You may obtain a copy of the License at 
+#
+# http://www.mozilla.org/MPL/
+# 
+# Software distributed under the License is distributed on an "AS IS" basis,
+# WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
+# the specificlanguage governing rights and  limitations under the License.
+# 
+# The Original Code is the FireRuby extension for the Ruby language.
+# 
+# The Initial Developer of the Original Code is Peter Wood. All Rights 
+# Reserved.
+#++
+#
+
+require 'iotaz/DatabaseInterfaceFactory'
+require 'iotaz/FirebirdInterface'
+require 'iotaz/IotazError'
+require 'iotaz/MetaData'
+require 'iotaz/ObjectPool'
+require 'iotaz/Persistent'
+require 'iotaz/Query'
+require 'iotaz/Session'
+require 'iotaz/WorkSet'
+
+module Iotaz
+   IOTAZ_VERSION = [0, 1, 0].join('.')
+end

data/lib/iotaz/DatabaseInterfaceFactory.rb

@@ -0,0 +1,92 @@
+#!/usr/bin/env ruby
+#
+#--
+# Copyright � Peter Wood, 2005
+# 
+# The contents of this file are subject to the Mozilla Public License Version
+# 1.1 (the "License"); you may not use this file except in compliance with the
+# License. You may obtain a copy of the License at 
+#
+# http://www.mozilla.org/MPL/
+# 
+# Software distributed under the License is distributed on an "AS IS" basis,
+# WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
+# the specificlanguage governing rights and  limitations under the License.
+# 
+# The Original Code is the FireRuby extension for the Ruby language.
+# 
+# The Initial Developer of the Original Code is Peter Wood. All Rights 
+# Reserved.
+#++
+#
+
+require 'thread'
+require 'iotaz/IotazError'
+require 'iotaz/FirebirdInterface'
+
+module Iotaz
+   #
+   # This class represents a factory object that will be used to manufacture
+   # the database interfaces used by the library.
+   #
+   class DatabaseInterfaceFactory
+      # The list of supported databases.
+      @@databases = ['FIREBIRD']
+      
+      
+      #
+      # This is the constructor for the DatabaseInterfaceFactory class. With
+      # regards to the configuration passed to this class, the factory is
+      # only interested in one value - iotaz.database. For the moment the only
+      # supported value for this is 'firebird'.
+      #
+      # ==== Parameters
+      # configuration::  A reference to a Hash object containing the
+      #                  configuration information for use by the factory
+      #                  object and the database interfaces that it will
+      #                  produce.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever the iotaz.database configuration entry is
+      #               not present or is set to an unsupported value.
+      #
+      def initialize(configuration)
+         if configuration.key?('iotaz.database')
+            name = configuration['iotaz.database'].upcase
+            if @@databases.include?(name) == false
+               raise IotazError.new("Unsupported database name specified for "\
+                                    "database interface factory. '{0}' is not "\
+                                    "the name of a supported database.")
+            end
+         else
+            raise IotazError.new('Database name missing from Iotaz configuration '\
+                                 'data.')
+         end
+         
+         @configuration = configuration
+      end
+      
+      
+      #
+      # This method manufactures a new database interface object using the
+      # configuration information provided to the factory.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated if any of the required configuration information
+      #               for the interface object is invalid.
+      #
+      def create
+         name      = @configuration['iotaz.database'].upcase
+         interface = nil
+         case name
+            when 'FIREBIRD' :
+               interface = FirebirdInterface.new(@configuration)
+            
+            else
+               raise IotazError.new("Error manufacturing database interface. "\
+                                    "Unknown database name '{0}' encountered.")
+         end
+         interface
+      end
+   end # End of the DatabaseInterfaceFactory class.
+end # End of the Iotaz module.

data/lib/iotaz/FirebirdInterface.rb

@@ -0,0 +1,788 @@
+#!/usr/bin/env ruby
+#
+#--
+# Copyright � Peter Wood, 2005
+# 
+# The contents of this file are subject to the Mozilla Public License Version
+# 1.1 (the "License"); you may not use this file except in compliance with the
+# License. You may obtain a copy of the License at 
+#
+# http://www.mozilla.org/MPL/
+# 
+# Software distributed under the License is distributed on an "AS IS" basis,
+# WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
+# the specificlanguage governing rights and  limitations under the License.
+# 
+# The Original Code is the FireRuby extension for the Ruby language.
+# 
+# The Initial Developer of the Original Code is Peter Wood. All Rights 
+# Reserved.
+#++
+#
+
+require 'iotaz/IotazError'
+require 'iotaz/ObjectPool'
+require 'iotaz/Session'
+require 'stringio'
+require 'rubygems'
+require_gem 'fireruby'
+
+include FireRuby
+
+module Iotaz
+   #
+   # This class manufactures or destroys connections to a specific Firebird
+   # database. This class is used internally by the connection pool within
+   # the FirebirdInterface class.
+   #
+   class FirebirdConnectionFactory
+      #
+      # This is the constructor fo the FirebirdConnectionFactory class.
+      #
+      # ==== Parameters
+      # user::      The user name to connect as.
+      # password::  The user password to be used to obtain connections.
+      # database::  The database file specification to be used to obtain
+      #             connections.
+      #
+      def initialize(user, password, database)
+         @database = Database.new(database)
+         @user     = user
+         @password = password
+      end
+      
+      
+      #
+      # This method is used to manufacture a new connection to the database.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever a problem occurs obtaining a new
+      #               database connection.
+      #
+      def create
+         @database.connect(@user, @password)
+      rescue FireRubyException => error
+         raise IotazError.new('Error opening new database connection. Cause: {0}',
+                              error.message)
+      end
+      
+      
+      #
+      # This method frees the resources associated with a connection previously
+      # created by the factory.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever a problem occurs closing the Firebird
+      #               connection.
+      #
+      def destroy(connection)
+         connection.close
+      rescue FireRubyException => error
+         raise IotazError.new('Error closing database connection. Cause: {0}',
+                              error.message)
+      end
+   end # End of the FirebirdConnectionFactory class
+   
+   
+   #
+   # This class represents the database interface for the Firebird database.
+   # The class makes use of the FireRuby library to interface with the database.
+   # The class currently recognises the following keys within the configuration
+   # data that is passed to it's constructor...
+   #
+   # - 'iotaz.firebird.user':
+   #   The user name to be used in connecting to the database. A value for this
+   #   entry must be specified.
+   #
+   # - 'iotaz.firebird.password':
+   #   The password to be used to connect to the database. A value for this
+   #   entry must be specified.
+   #
+   # - 'iotaz.firebird.database':
+   #   The database file specification to be used to connect to the database. A
+   #   value for this entry must be specified.
+   #
+   # - 'iotaz.firebird.connections.max':
+   #   The maximum number of connections to be pooled by the interface. If not
+   #   specified a default of 5 is used.
+   #
+   # - 'iotaz.firebird.connections.min':
+   #   The minimum number of connections that the interface will have available
+   #   in its connection pool. If not specified a default of 2 is used.
+   #
+   # - 'iotaz.firebird.connections.idle':
+   #   The amount of time, in seconds, that a pooled connection can remain idle
+   #   before it can be considered for automatic release. If not specified a
+   #   default of 1800 is used.
+   #
+   # - 'iotaz.firebird.connections.interval':
+   #   The interval, in seconds, that the interface will wait between attempts
+   #   to clean up idle connections. If not specified a default of 300 is used.
+   #
+   class FirebirdInterface
+      # A definition for the configuration keys recognised by the class.
+      KEYS = ['iotaz.firebird.user',
+              'iotaz.firebird.password',
+              'iotaz.firebird.database',
+              'iotaz.firebird.connections.max',
+              'iotaz.firebird.connections.min',
+              'iotaz.firebird.connections.idle',
+              'iotaz.firebird.connections.interval']
+              
+              
+      #
+      # This is the constructor for the FirebirdInterface class.
+      #
+      # ==== Parameters
+      # config::  A hash containing the configuration elements for the interface.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever a required configuration element is not
+      #               provided.
+      #
+      def initialize(config)
+         # Check for required values.
+         if config.key?(KEYS[0]) == false
+            raise IotazError.new("Require database interface configuration "\
+                                 "element '{0}' not specified.", KEYS[0])
+         end
+         if config.key?(KEYS[1]) == false
+            raise IotazError.new("Require database interface configuration "\
+                                 "element '{0}' not specified.", KEYS[1])
+         end
+         if config.key?('iotaz.firebird.database') == false
+            raise IotazError.new("Require database interface configuration "\
+                                 "element '{0}' not specified.", KEYS[2])
+         end
+         
+         # Extract the required elements.
+         user     = config[KEYS[0]]
+         password = config[KEYS[1]]
+         database = config[KEYS[2]]
+         
+         # Create the interface connection pool.
+         factory  = FirebirdConnectionFactory.new(user, password, database)
+         maximum  = config.key?(KEYS[3]) ? config[KEYS[3]].to_i : 5
+         minimum  = config.key?(KEYS[4]) ? config[KEYS[3]].to_i : 2
+         idle     = config.key?(KEYS[5]) ? config[KEYS[3]].to_i : 1800
+         interval = config.key?(KEYS[6]) ? config[KEYS[3]].to_i : 300
+         @pool    = ObjectPool.new(factory, maximum, minimum, idle, interval)
+         at_exit {@pool.shutdown}
+      end
+
+
+      #
+      # This method generates the SQL statement for the insertion of a new
+      # row into a database table based on a meta-data set and an object
+      # value. The function returns three values, the first is the SQL statement
+      # for the insertion. The second is an array of the callback objects that
+      # will be used to populate data values that will be available after the
+      # SQL execution. The third is an array of the parameter values to be used
+      # in conjunction with the SQL.
+      #
+      # ==== Parameters
+      # object::    A reference to the object to generate the insertion SQL
+      #             statement for. This must be an instance of a class that
+      #             implements the iotaz_meta_data method.
+      #
+      def get_insert_sql(object)
+         text       = [StringIO.new, StringIO.new]
+         callbacks     = []
+         parameters = []
+         metadata   = object.class.iotaz_meta_data
+         
+         # Insert the initial callbacks for the aspects of the SQL statement.
+         text[0] << "insert into #{metadata.table}("
+         text[1] << "values("
+         
+         # Iterate over the attribute definitions.
+         added = false
+         metadata.each do |attribute|
+            # Check if the attribute is to be generated.
+            if attribute.is_generated?
+               # Check if the value is generated for inserts.
+               if attribute.events.include?("INSERT")
+                  name   = attribute.name
+                  source = attribute.source
+                  case attribute.type
+                     when 'SEQUENCE' :
+                        # Added the details to the SQL statement.
+                        text[0] << ", " if added
+                        text[0] << attribute.column
+                        text[1] << ", " if added
+                        text[1] << "?"
+                        number = get_sequence_value(source)
+                        parameters.push(number)
+                        attribute.set(object, number)
+                        added = true if added == false
+                     when 'DATE', 'TIME', 'TIMESTAMP' :
+                        # Generate an value callback to get the value assigned.
+                        sql = get_value_select(attribute.name, object)
+                        callbacks.push(ValueCallback.new(object,
+                                                         attribute.name,
+                                                         sql))
+                        
+                        # Update the SQL statement.
+                        text[0] << ", " if added
+                        text[0] << attribute.column
+                        text[1] << ", " if added
+                        text[1] << "'#{attribute.source}'"
+                        added = true if added == false
+                  end
+               end
+            else
+               # Add the column name.
+               text[0] << ", " if added
+               text[0] << attribute.column
+               
+               # Add the column value.
+               text[1] << ", " if added
+               text[1] << "?"
+               parameters.push(attribute.get(object))
+               added = true if added == false
+            end
+         end
+         
+         # Terminate the aspects of the SQL statement.
+         text[0] << ") "
+         text[1] << ")"
+         
+         #puts "INSERT SQL: #{text[0].string}#{text[1].string}"
+         #puts "PARAMETERS: #{parameters.join(', ')}"
+         [text[0].string + text[1].string, callbacks, parameters]
+      end
+
+
+      #
+      # This method generates the SQL statement for the update of an existing
+      # row into a database table based on a meta-data set and an object
+      # value. The function returns two values, the firsr is the SQL statement
+      # for the update. The second is a hash of generated values, mapping
+      # attribute names to generated values. This hash will either contain
+      # the generated value or a ValueCallback if the value will only be
+      # available after the statement has been executed.
+      #
+      # ==== Parameters
+      # object::    A reference to the object to generate the insertion SQL
+      #             statement for. This must be an instance of a class that
+      #             implements the iotaz_meta_data method.
+      #
+      def get_update_sql(object)
+         sql        = StringIO.new
+         values     = []
+         parameters = []
+         metadata   = object.class.iotaz_meta_data
+         
+         # Insert the initial values for the aspects of the SQL statement.
+         sql << "update #{metadata.table} set "
+         
+         # Iterate over the attribute definitions.
+         added = false
+         metadata.each do |attribute|
+            # Check if the attribute is to be generated.
+            if attribute.is_generated?
+               # Check if the value is generated for inserts.
+               if attribute.events.include?("UPDATE")
+                  name   = attribute.name
+                  source = attribute.source
+                  case attribute.type
+                     when 'SEQUENCE' :
+                        # Added the details to the SQL statement.
+                        sql << ", " if added
+                        sql << attribute.column << " = ?"
+                        number = get_sequence_value(source)
+                        parameters.push(number)
+                        attribute.set(object, number)
+                        added = true if added == false
+                        
+                     when 'DATE', 'TIME', 'TIMESTAMP' :
+                        # Generate an value callback to get the value assigned.
+                        statement = get_value_select(attribute.name, object)
+                        values.push(ValueCallback.new(object,
+                                                      attribute.name,
+                                                      statement))
+                        
+                        # Update the SQL statement.
+                        sql << ", " if added
+                        sql << attribute.column << " = '#{attribute.source}'"
+                        added = true if added == false
+                  end
+               end
+            else
+               # Add the column name and value.
+               sql << ", " if added
+               sql << attribute.column << " = ?"
+               parameters.push(attribute.get(object))
+               added = true if added == false
+            end
+         end
+         
+         # Terminate the aspects of the SQL statement.
+         sql << " " << get_key_sql(object)
+         parameters.concat(get_key_values(object))
+         
+         #puts "UPDATE SQL: #{sql.string}"
+         #puts "PARAMETERS: #{parameters.join(', ')}"
+         [sql.string, values, parameters]
+      end
+      
+      
+      #
+      # This method produces the SQL select statement that can be used to
+      # fetch an object instance for a given class from the database.
+      #
+      # ==== Parameters
+      # klass::  A reference to the class of the object that will be fetched
+      #          from the database.
+      #
+      def get_fetch_sql(klass)
+         metadata = klass.iotaz_meta_data
+         sql      = StringIO.new
+         added    = false
+         
+         # Load details of the attributes.
+         sql << "select "
+         metadata.each do |attribute|
+            sql << ', ' if added
+            sql << attribute.column
+            added = true if added == false
+         end
+         sql << " from #{metadata.table} #{get_key_sql(klass)}"
+         
+         #puts "FETCH SQL: #{sql.string}"
+         sql.string
+      end
+      
+      
+      #
+      # This method produces the SQL statement that can be used to delete the
+      # database record for an object.
+      #
+      # ==== Parameters
+      # object::  Either a reference to an object or to a Class instance. If it
+      #           is a Class instance then the class must implement the
+      #           iotaz_meta_data method. If it's just a normal object then
+      #           the objects class must implement the method.
+      #
+      def get_delete_sql(object)
+         metadata = nil
+         if object.instance_of?(Class)
+            metadata = object.iotaz_meta_data
+         else
+            metadata = object.class.iotaz_meta_data
+         end
+         #puts "DELETE SQL: delete from #{metadata.table} #{get_key_sql(object)}"
+         "delete from #{metadata.table} #{get_key_sql(object)}"
+      end
+      
+      
+      #
+      # This method initiates a transaction within the database. The value
+      # that is returned by the method should not be interpreted outside of
+      # this class.
+      #
+      def start_transaction
+         [@pool.acquire, nil]
+      end
+      
+      
+      #
+      # This method commits a transaction previously created using a call to the
+      # FirebirdInterface#start_transaction method.
+      #
+      # ==== Parameters
+      # transaction::  A reference to the transaction details to be committed.
+      #
+      # ==== Exception
+      # IotazError::  Generated whenever a problem occurs committing the work
+      #               for the transaction.
+      #
+      def commit(transaction)
+         begin
+            transaction[1].commit if transaction[1] != nil
+            @pool.release(transaction[0])
+            transaction[0] = transaction[1] = nil
+         rescue FireRubyException => error
+            raise IotazError.new("Exception caught committing transaction. "\
+                                 "Cause: {0}", error.message)
+         end
+      end
+      
+      
+      #
+      # This method rolls back a transaction created using a call to the
+      # FirebirdInterface#start_transaction method.
+      #
+      # ==== Parameters
+      # transaction::  A reference to the transaction details to be rolled back.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever a problem occurs rolling back the work
+      #               for the transaction.
+      #
+      def rollback(transaction)
+         begin
+            transaction[1].rollback if transaction[1] != nil
+            @pool.release(transaction[0])
+            transaction[0] = transaction[1] = nil
+         rescue FireRubyException => error
+            raise IotazError.new("Exception caught rolling back transaction. "\
+                                 "Cause: {0}", error.message)
+         end
+      end
+      
+      
+      #
+      # This method executes a single unit of work represented by an Action
+      # object.
+      #
+      # ==== Parameters
+      # action::       A reference to the action to be executed.
+      # transaction::  A reference to the transaction entity to be used in the
+      #                execution. This should have been previously obtained
+      #                from a call to the start_transaction method.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever a problem occurs executing the work for
+      #               the action.
+      #
+      def execute_action(action, transaction)
+         begin
+            # Check if a transaction needs to be started.
+            if transaction[1] == nil
+               transaction[1] = transaction[0].start_transaction
+            end
+            
+            # Check if we've cached anything for this action.
+            statement = nil
+            if action.cache == nil
+               statement = Statement.new(transaction[0], transaction[1],
+                                         action.sql, 3)
+               action.cache = statement
+            else
+               statement = action.cache
+            end
+            
+            # Execute the statement on a parameter set.
+            parameters = action.get_parameters
+            result     = statement.execute_for(parameters)
+            result.close if result != nil
+         rescue FireRubyException => error
+            raise IotazError.new("Exception caught executing action. Cause: {0}",
+                                 error.message)
+         end
+      end
+      
+      
+      #
+      # This method executes a select statement to fetch the data for a value
+      # callback.
+      #
+      # ==== Parameters
+      # callback::     A reference to the ValueCallback object to be executed.
+      # transaction::  A reference to the transaction entity to be used in the
+      #                execution. This should have been previously obtained
+      #                from a call to the start_transaction method.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever a problem occurs executing the SQL for
+      #               the callback object.
+      #
+      def execute_callback(callback, transaction)
+         data = nil
+         begin
+            # Check if a transaction has actually been started.
+            if transaction[1] == nil
+               transaction[1] = transaction[0].start_transaction
+            end
+            
+            # Execute the fetch and check the result.
+            statement = nil
+            if callback.cache == nil
+               statement      = Statement.new(transaction[0], transaction[1],
+                                              callback.sql, 3)
+               callback.cache = statement
+            else
+               statement = callback.cache
+            end
+            
+            result = statement.execute_for(callback.parameters)
+            if result == nil
+               raise IotazError.new("Value callback SQL statement did not "\
+                                    "return a result set.")
+            end
+            
+            # Extract the data and clean up.
+            data = result.fetch[0]
+            result.close
+         rescue FireRubyException => error
+            raise IotazError.new("Error executing value callback. Cause: {0}",
+                                 error.message)
+         end
+         data
+      end
+      
+      
+      #
+      # This method executes a SQL query, passed in the form of a Query object,
+      # against the database.
+      #
+      # ==== Parameters
+      # query::        A reference to the Query object that will provide the
+      #                details for the query to execute.
+      # transaction::  A reference to the transaction entity, previously created
+      #                by a call to the start_transaction method, that will be
+      #                used to execute the query.
+      # maximum::      A reference to an integer indicating the maximum number
+      #                of rows to fetch. This defaults to -1 to indicate that
+      #                all rows for the query should be returned.
+      #
+      def execute_query(query, transaction, maximum=-1)
+         rows = []
+         
+         # Check that the transaction entity is fully initialized.
+         if transaction[1] == nil
+            transaction[1] = transaction[0].start_transaction
+         end
+         
+         # Extract the query details.
+         sql, parameters = query.to_sql
+         
+         # Create the statement.
+         statement = Statement.new(transaction[0], transaction[1], sql, 3)
+         begin
+            # Get the result set.
+            results = statement.execute_for(parameters)
+            begin
+               if maximum > 0
+                  1.upto(maximum) do |index|
+                     entry = results.fetch
+                     if entry != nil
+                        row = QueryRow.new
+                        0.upto(entry.column_count - 1) do |index|
+                           row[entry.column_name(index)] = entry[index]
+                        end
+                        rows.push(row)
+                     else
+                        break;
+                     end
+                  end
+               else
+                  results.each do |entry|
+                     row = QueryRow.new
+                     0.upto(entry.column_count - 1) do |index|
+                        row[entry.column_name(index)] = entry[index]
+                     end
+                     rows.push(row)
+                  end
+               end
+            ensure
+               results.close
+            end
+         ensure
+            statement.close
+         end
+         
+         rows
+      end
+      
+      
+      #
+      # This method executes a SQL select statement, returning the rows fetched
+      # as a result. This method returns an array of hashes. Each contained
+      # hash represents a row of data from the select statement, mapping
+      # column names onto column values. Column names are set to be all upper
+      # case to simplify comparisons.
+      #
+      # ==== Parameters
+      # sql::          A string containing the SQL statement to be executed.
+      # parameters::   An array containing the parameters to be used in
+      #                executing the SQL.
+      # transaction::  A reference to the transaction entity that will be used
+      #                in executing the select. 
+      # maximum::      An integer specifying the maximum number of rows to be
+      #                fetched. This defaults to -1 to indicate that all rows
+      #                should be fetched.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever a invalid number of parameters are
+      #               specified, the SQL statement provided does not represent a
+      #               select or an error occurs accessing the database.
+      #
+      def execute_select(sql, parameters, transaction, maximum=-1)
+         rows = []
+         
+         # Check if a transaction is needed.
+         if transaction[1] == nil
+            transaction[1] = transaction[0].start_transaction
+         end
+         
+         # Create the statement to execute the SQL.
+         statement = Statement.new(transaction[0], transaction[1], sql, 3)
+         if statement.is_query? == false
+            raise IotazError.new("Invalid SQL query. '{0}' is not a SQL select "\
+                                 "statement.", sql)
+         end
+         
+         results = nil
+         begin
+            results = statement.execute_for(parameters)
+            if maximum > 0
+               count = 0
+               while count < maximum and rows.size == count
+                  row = results.fetch
+                  if row != nil
+                     map = Hash.new
+                     row.each_index do |index|
+                        map[results.column_name(index).upcase] = row[index]
+                     end
+                     rows.push(map)
+                  end
+                  count += 1
+               end
+            else
+               results.each do |row|
+                  map = Hash.new
+                  
+                  0.upto(row.column_count - 1) do |index|
+                     map[row.column_name(index).upcase] = row[index]
+                  end
+                  rows.push(map)
+               end
+            end
+         ensure
+            results.close if results != nil
+         end
+         
+         rows
+      rescue FireRubyException => error
+         raise IotazError.new('Error executing select. Cause: {0}',
+                              error.message)
+      end
+      
+      
+      #
+      # This method is used to clean up the items assigned to Action cache
+      # values as part of the work of executing the action.
+      #
+      # ==== Parameters
+      # cache::  An array of the cache items that are to be cleaned up.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever a problem is encountered cleaning up a
+      #               cache item.
+      #
+      def clean_cache(cache)
+         begin
+            cache.each {|entry| entry.close if entry != nil}
+         rescue FireRubyException => error
+            raise IotazError.new("Error cleaning up cache item. Cause: {0}",
+                                 error.message)
+         end
+      end
+      
+      
+      #
+      # This method fetches the next value from a name Firebird generator.
+      #
+      # ==== Parameters
+      # sequence::  The name of the generator to fetch the value.
+      #
+      def get_sequence_value(sequence)
+         value = nil
+         @pool.acquire do |connection|
+            sequence = Generator.new(sequence, connection)
+            value    = sequence.next(1)
+         end
+         value
+      end
+      
+      
+      #
+      # This method produces a SQL select statement to fetch a value from
+      # a specific database row.
+      #
+      # ==== Parameters
+      # name::     The name of the attribute to generate the select for.
+      # object::   The object to get the key values from. This must be an
+      #            instance of a class that implements the iotaz_meta_data
+      #            method.
+      #
+      def get_value_select(name, object)
+         metadata  = object.class.iotaz_meta_data
+         attribute = metadata.get_attribute(name)
+         "select #{attribute.column} from #{metadata.table} #{get_key_sql(object)}"
+      end
+      
+      
+      #
+      # This method generates the where clause aspects of a SQL statement to
+      # uniquely pick out a database row for a given object. The SQL fragement
+      # returned by the method will not fill out the key ookup fields, providing
+      # substitution entries instead. This is done as the lookup of the key
+      # values is left to the latest possible moment.
+      #
+      # ==== Parameters
+      # object::  Either a reference to the object to generate the SQL statement
+      #           clauses for or a Class instance. If an object is specified
+      #           then its class must provides the iotaz_meta_data method. If
+      #           its a class then it must have a iotaz_meta_data method.
+      #
+      def get_key_sql(object)
+         out      = StringIO.new
+         metadata = nil
+         if object.instance_of?(Class)
+            metadata = object.iotaz_meta_data
+         else
+            metadata = object.class.iotaz_meta_data
+         end
+         
+         added = false
+         out << 'where '
+         metadata.keys.each do |key|
+            attribute = metadata.get_attribute(key)
+            out << " and " if added
+            out << attribute.column << " = ?"
+            added = true if added == false
+         end
+         
+         out.string
+      end
+      
+      
+      #
+      # This method looks up the values of the parameters associated with the
+      # keys for an object. The method returns an array of the values for the
+      # key attributes for the object.
+      #
+      # ==== Parameters
+      # object::  The object to look up the key values for. This must be an
+      #           instance of a class that implements the iotaz_meta_data
+      #           method.
+      #
+      def get_key_values(object)
+         values   = []
+         metadata = object.class.iotaz_meta_data
+         
+         metadata.keys.each do |key|
+            values.push(metadata.get_attribute(key).get(object))
+         end
+         
+         values
+      end
+      
+      
+      #
+      # This method shutdown an instance of the FirebirdInterface class. The
+      # object that this method is called for should not be used again after
+      # making the call.
+      #
+      def shutdown
+         @pool.shutdown
+      end
+      
+      
+      # Method access alterations.
+      private :get_value_select
+   end # End of the Firebird interface class.
+end # End of the Iotaz module.