iotaz 0.1.0

data/lib/iotaz/Session.rb

@@ -0,0 +1,379 @@
+#!/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/WorkSet'
+require 'iotaz/FirebirdInterface'
+require 'thread'
+
+module Iotaz
+   #
+   # This class represents a session of interaction with the persistence
+   # mechanism.
+   #
+   class Session
+      #
+      # This is the constructor for the Session class.
+      #
+      # ==== Parameters
+      # interface::  A reference to the database interface object that the
+      #              session will be linked to.
+      # listener::   A reference to an object that is interested in knowing
+      #              if the session is terminated. This is used to allow the
+      #              SessionFactory class to monitor available sessions. The
+      #              object specified must implement a terminating method that
+      #              will be invoked when the session is terminated. This
+      #              defaults to nil to indicate no interested object.
+      #
+      def initialize(interface, listener=nil)
+         @interface = interface
+         @listener  = listener
+         @atom      = nil
+      end
+      
+      
+      #
+      # This method initializes a transaction within a session. The method
+      # accepts a block that delimits the lifetime of the transaction.
+      #
+      def start_transaction
+         @atom = Atom.new
+         if block_given?
+            begin
+               yield
+               commit
+            rescue
+               rollback
+            end
+         end
+      end
+      
+      
+      #
+      # This method invalidates a session, releasing it resources. After a call
+      # to this method a Session object should no longer be used.
+      #
+      def terminate
+         @listener.terminating(self) if @listener != nil
+         @interface = @atom = nil
+      end
+      
+      
+      #
+      # This method attempts to commit any outstanding transaction.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever a problem occurs committing the work
+      #               for the transaction.
+      #
+      def commit
+         @atom.commit(@interface)
+         @atom = nil                  
+      end
+      
+      
+      #
+      # This method attempts to roll back any outstanding transaction.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever a problem occurs rolling back the work
+      #               for the transaction.
+      #
+      def rollback
+         @atom = nil
+      end
+      
+      
+      #
+      # This method saves the details for an object to persistent store. If
+      # a transaction is active the actual push to the database is differed
+      # until a commit.
+      #
+      # ==== Parameters
+      # object::  A reference to the object to be saved.
+      #
+      def save(object)
+         metadata = object.class.iotaz_meta_data
+         saved    = true
+         
+         # Check if the object class key is nil.
+         metadata.keys.each do |key|
+            attribute = metadata.get_attribute(key)
+            if attribute.is_generated?
+               saved = false if attribute.get(object) == nil 
+            end             
+            break if saved == false
+         end
+         
+         # Create the action for the save.
+         action = callbacks = nil
+         if saved
+            sql, callbacks, parameters = @interface.get_update_sql(object)
+         else
+            # Generate the action to save the object.
+            sql, callbacks, parameters = @interface.get_insert_sql(object)
+         end
+         action = Action.new(sql)
+         action.add_parameters(*parameters)
+         
+         # Check if a transaction is active.
+         if @atom == nil
+            execute_immediate(action, *callbacks)
+         else
+            @atom.add(action, *callbacks)
+         end
+      end
+      
+      
+      #
+      # This method is used to load an object from the database based on its
+      # keys values.
+      #
+      # ==== Parameters
+      # klass::       The class of the object that will be loaded. This class
+      #               must provide an iotaz_load method the creates an instance of
+      #               the class from an data set loaded from the database.
+      # parameters::  An array of the parameters that for the key values to be
+      #               used to access the specified record.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever insufficient parameters are provided,
+      #               the select fetches more than one row or a problem occurs
+      #               accessing the database.
+      #
+      def load(klass, *parameters)
+         sql         = @interface.get_fetch_sql(klass)
+         transaction = @interface.start_transaction
+         begin
+            # Fetch the record data.
+            rows = @interface.execute_select(sql, parameters, transaction)
+            if rows.size > 1
+               raise IotazError.new("Error loading a '{0}' class instance. Key "\
+                                    "matches more than one row in the database.",
+                                    klass.name)
+            elsif rows.size == 0
+               raise IotazError.new("Error loading a '{0}' class instance. "\
+                                    "Object not found in database.",
+                                    klass.name)
+            end
+            @interface.commit(transaction)
+            transaction = nil
+
+            # Create and populate the object instance.
+            klass.iotaz_meta_data.populate(klass.allocate, rows[0])
+         ensure
+            @interface.rollback(transaction) if transaction != nil
+         end
+      end
+      
+      
+      #
+      # This method deletes the database record for an object from the database.
+      #
+      # ==== Parameters
+      # object::  A reference to the object to be deleted.
+      #
+      def delete(object)
+         metadata = object.class.iotaz_meta_data
+         action   = Action.new(@interface.get_delete_sql(object))
+         action.add_parameters(*metadata.get_key_values(object))
+         
+         if @atom == nil
+            execute_immediate(action)
+         else
+            @atom.add(action)
+         end
+      end
+      
+      
+      #
+      # This method executes a Query object using a Session object. The method
+      # returns an array of QueryRow objects.
+      #
+      # ==== Parameters
+      # query::    A reference to the Query object that will be executed.
+      # maximum::  An integer specifying the maximum number of rows to be
+      #            retrieved. Defaults to -1 to indicate a fetch of all rows.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever a problem occurs executing the query.
+      #
+      def execute(query, maximum=-1)
+         rows        = nil
+         transaction = @interface.start_transaction
+         
+         begin
+            rows = @interface.execute_query(query, transaction, maximum)
+            @interface.commit(transaction)
+         rescue IotazError => error
+            @interface.rollback(transaction)
+            raise error
+         end
+         
+         rows
+      end
+      
+      
+      #
+      # This method processes a single action and it's related callbacks at
+      # once, as opposed to making them part of a transaction. This is almost
+      # like using SQL with an auto-commit function.
+      #
+      # ==== Parameters
+      # action::     A reference to the action to be executed.
+      # callbacks::  An array of the callback values to be executed to.
+      #
+      def execute_immediate(action, *callbacks)
+         transaction = @interface.start_transaction
+         begin
+            @interface.execute_action(action, transaction)
+            callbacks.each do |entry|
+               data = @interface.execute_callback(entry, transaction)
+               entry.assign(data)
+            end
+            @interface.commit(transaction)
+            transaction = nil
+         rescue IotazError => error
+            @interface.rollback(transaction)
+            raise error
+         end
+      end
+      
+      
+      # Method access alterations.
+      private :execute_immediate
+   end # End of the Session class.
+   
+   
+   #
+   # This class represents a means of generating Session objects. The class
+   # helps abstract away from the concept of a database and allows for later
+   # expansion of the library to support other databases. The constructor for
+   # the class takes a hash containing configuration data as a parameter. Most
+   # of this data is for the database interface that will sit behind the factory
+   # object but an entry for the 'iotaz.database' key is used by the factory class
+   # to determine which database is to be used and must, therefore, be provided.
+   #
+   class SessionFactory
+      #
+      # This is the constructor for the SessionFactory class. From the details
+      # of the configuration data passed to it this method constructs a factory
+      # class instance geared to a particular database. The only database that
+      # is currently supported is Firebird but this may change in the future.
+      #
+      # ==== Parameters
+      # configuration::  A hash containing the configuration elements to be
+      #                  used by the session factory. As Firebird is the only
+      #                  currently supported RDBMS refer to the
+      #                  FirebirdInterface class for the full set of valid
+      #                  configuration parameters.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever an unknown database is specified or
+      #               the configuration specified is incomplete.
+      #
+      def initialize(configuration)
+         # Create the interface class instance.
+         @interface = get_interface_class(configuration).new(configuration)
+         @sessions  = []
+         @mutex     = Mutex.new
+         
+         # Clear out sessions on exit.
+         at_exit {@sessions.each {|session| session.terminate}}
+      end
+      
+      
+      #
+      # This method is used to have the factory object create a new Session.
+      #
+      def start
+         session = Session.new(@interface, self)
+         @mutex.synchronize {@sessions.push(session)}
+         session
+      end
+      
+      
+      #
+      # This method is used to terminate a session factory whenever it is no
+      # longer needed. This should be called to release the resources for a
+      # factory.
+      #
+      def shutdown
+         @interface.shutdown
+      end
+      
+      
+      #
+      # This method is used by the sessions produced by the factory to inform
+      # the factory that the session is being terminated. This method should
+      # not be used except in this context.
+      #
+      # ==== Parameters
+      # session::  A reference to the Session object being terminated.
+      #
+      def terminating(session)
+         @mutex.synchronize {@sessions.delete(session)}
+      end
+      
+      
+      #
+      # This method retrieves the database interface class associated with a
+      # given configuration.
+      #
+      # ==== Parameters
+      # configuration::  The configuration that will be used to determine the
+      #                  database interface class to use. This hash of values
+      #                  will be searched for an entry with the 'iotaz.database'
+      #                  key and the value of this entry used to determine the
+      #                  interface class to use.
+      #
+      # ==== Exception
+      # IotazError::  Generated whenever the required configuration entry is not
+      #               present or contains a value for an unknown database.
+      #
+      def get_interface_class(configuration)
+         klass = nil
+         
+         if configuration.key?('iotaz.database') == false
+            raise IotazError.new("Invalid session factory configuration. The "\
+                                 "specified configuration is missing an entry "\
+                                 "for '{0}'.", 'iotaz.database')
+         end
+         
+         case configuration['iotaz.database'].upcase
+            when 'FIREBIRD' :
+               klass = FirebirdInterface
+            
+            else
+               raise IotazError.new("Unknown or unsupported database specified "\
+                                    "for session factory. '{0}' is not a "\
+                                    "recognised or supported database.",
+                                    configuration['iotaz.database'])
+         end
+         
+         klass
+      end
+      
+      
+      # Method access alterations.
+      private :get_interface_class
+   end # End of the SessionFactory class.
+end # End of the Iotaz module.

data/lib/iotaz/WorkSet.rb

@@ -0,0 +1,295 @@
+#!/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'
+
+module Iotaz
+   #
+   # This class represents a SQL statement and multiple potential parameter
+   # data sets for the execution of the statement. The cache attribute is
+   # intended for use by the database functionality to allow the Action object
+   # to be re-used as much as possible.
+   #
+   class Action
+      #
+      # This is the constructor for the Action class.
+      #
+      # ==== Parameters
+      # sql::  A string containing the SQL to be executed for the action.
+      #
+      def initialize(sql)
+         @sql   = sql
+         @index = 0
+         @data  = Array.new
+         @cache = nil
+      end
+      
+      
+      #
+      # This method fetches the next set of parameters from an Action object.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever the method is called on an action that
+      #               has exhausted it's available parameter sets.
+      #
+      def get_parameters
+         if @index == @data.size
+            raise IotazError.new('Parameter set requested from exhausted action.')
+         end
+         @index += 1
+         @data[@index - 1]
+      end
+      
+      
+      #
+      # This method adds a new set of parameters to an Action object.
+      #
+      # ==== Parameters
+      # parameters::  An array containing the new parameter set.
+      #
+      def add_parameters(*parameters)
+         @data.push(parameters)
+      end
+      
+      
+      # Class attribute accessor.
+      attr_reader :sql, :data, :cache
+      
+      # Class attribute mutator.
+      attr_writer :cache
+   end # End of the Action class.
+
+
+   #
+   # This class represents a value that must be fetched back from a database
+   # for a generated column. This consists of the SQL statement to fetch the
+   # value plus a reference to the object that the value goes into and details
+   # of how to get it into the object. To allow for optimizations an instance
+   # of the ValueCallback object may refer to more than a single object. In
+   # this case care should be taken with using the object. A ValueCallback that
+   # contains more than one object behaves differently in it's use of the
+   # parameters and assign methods. A call to the parameters method returns a
+   # parameter set for the current object and then advances it to the next
+   # available object. A call to assign will assign a value to the last object
+   # used to provide a parameter set.
+   #
+   class ValueCallback
+      #
+      # This is the constructor for the ValueCallback class.
+      #
+      # ==== Parameters
+      # object::     A reference to the object that the value will go back
+      #              into.
+      # attribute::  The name of the attribute that the callback will be used
+      #              to provide a value for.
+      # sql::        A string containing the SQL statement to fetch the object
+      #              value.
+      #
+      def initialize(object, attribute, sql)
+         @objects   = [object]
+         @current   = 1
+         @attribute = attribute
+         @sql       = sql
+         @cache     = nil
+      end
+      
+      
+      #
+      # This method fetches the current object for a ValueCallback instance.
+      # The method does not advance the object reference.
+      #
+      def object
+         @objects[@current - 1]
+      end
+      
+      
+      #
+      # This method adds another object that will be covered by the callback
+      #
+      # ==== Parameters
+      # object::  A reference to the object that will be added to the callback.
+      #
+      def add_object(object)
+         @objects.push(object)
+      end
+      
+      
+      #
+      # This method assigns the generated value into the object.
+      #
+      # ==== Parameters
+      # value::  A reference to the generated value for the object.
+      #
+      def assign(value)
+         object   = @objects[@current - 2]
+         metadata = object.class.iotaz_meta_data
+         metadata.get_attribute(@attribute).set(object, value)
+      end
+      
+      
+      #
+      # This method fetches the data set required to execute the SQL statement
+      # associated with a callback.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever any of the key attribute values for the
+      #               object are nil.
+      #
+      def parameters
+         parameters = []
+         object     = @objects[@current - 1]
+         @curent    = @current + 1
+         metadata   = object.class.iotaz_meta_data
+         
+         metadata.keys.each do |key|
+            value = metadata.get_attribute(key).get(object)
+            if value == nil
+               raise IotazError.new("Value callback parameter key value is nil.")
+            end
+            parameters.push(value)
+         end
+         parameters
+      end
+      
+      
+      # Class attribute accessor.
+      attr_reader :objects, :attribute, :sql, :cache
+      
+      # Class attribute mutator.
+      attr_writer :cache
+   end # End of the ValueCallback class.
+   
+   
+   #
+   # This class represents a series of SQL statements making up an atomic
+   # set of work.
+   #
+   class Atom
+      #
+      # This is the constructor for the Atom class.
+      #
+      def initialize
+         @actions   = []
+         @callbacks = []
+      end
+      
+      
+      #
+      # This method adds a new action and call back set to the atom.
+      #
+      # ==== Parameters
+      # action::     An action reflecting the task that will be executed as
+      #              as part of the Atom.
+      # callbacks::  An array of the callback that go along with the action
+      #              being added.
+      #
+      def add(action, *callbacks)
+         # Store the action.
+         match = @actions.find {|entry| entry.sql == action.sql}
+         if match != nil
+            match.add_parameters(*action.get_parameters)
+            @actions.push(match)
+         else
+            @actions.push(action)
+         end
+         
+         # Store the callbacks.
+         callbacks.each do |entry|
+            match = @callbacks.find {|callback| callback.sql == entry.sql}
+            if match != nil
+               match.add_object(entry.object)
+               @callbacks.push(match)
+            else
+               @callbacks.push(entry)
+            end
+         end
+      end
+      
+      
+      #
+      # This method fetches a count of the total number of actions currently
+      # stored within an Atom object.
+      #
+      def action_count
+         @actions.size
+      end
+      
+      
+      #
+      # This method fetches a count of the total number of value callbacks
+      # currently stored within an Atom object.
+      #
+      def callback_count
+         @callbacks.size
+      end
+      
+      
+      #
+      # This method attempts to commit the work within an Atom object to the
+      # database.
+      #
+      # ==== Parameters
+      # interface::  A reference to the database interface object to be used
+      #              to execute the work.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever a problem occurs executing the actions
+      #               or callbacks for the Atom object.
+      #
+      def commit(interface)
+         transaction = nil
+         begin
+            # Start a transaction and execute the actions.
+            transaction = interface.start_transaction
+            @actions.each do |entry|
+               interface.execute_action(entry, transaction)
+            end
+            
+            # Execute the value callbacks to update objects.
+            @callbacks.each do |entry|
+               entry.assign(interface.execute_callback(entry, transaction))
+            end
+            
+            # Clean up cached items.
+            items = []
+            @actions.each do |entry|
+               items.push(entry.cache) if entry.cache != nil
+            end
+            @callbacks.each do |entry|
+               items.push(entry.cache) if entry.cache != nil
+            end
+            interface.clean_cache(items)
+            
+            # Commit the transaction.
+            interface.commit(transaction)
+            transaction = nil
+         rescue IotazError => error
+            raise error
+         rescue Exception => error
+            raise IotazError.new("Error committing work atom, Cause: {0}",
+                                 error.message)
+         ensure
+            interface.rollback(transaction) if transaction != nil
+         end
+      end
+   end # End of the Atom class.
+end # End of the Iotaz module.