iotaz 0.1.0

data/lib/iotaz/IotazError.rb

@@ -0,0 +1,81 @@
+#!/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.
+#++
+#
+
+module Iotaz
+   #
+   # This class represents the base exception class used throughout the Iotaz
+   # library code.
+   #
+   class IotazError < StandardError
+      #
+      # This is the constructor for the IotazError class.
+      #
+      # ==== Parameters
+      # message::  The base error message associated with the exception.
+      # context::  An array of any remaining parameters passed to the class
+      #            initializer. These will be treated as context details that
+      #            will be used to populate the message generated.
+      #
+      def initialize(message, *context)
+         @message = message
+         @context = context
+      end
+      
+      
+      #
+      # This method creates a copy of the context details for an IotazError
+      # object.
+      #
+      def context
+         [].concat(@context)
+      end
+      
+      
+      #
+      # This method generates the error message associated with an IotazError
+      # object.
+      #
+      def message
+         populate(@message)
+      end
+      
+      
+      #
+      # This method populates an input string with the context details for a
+      # IotazError object. This population is achieved by the substitution of
+      # tokens within the input string. Tokens take the form of {n}, where
+      # n is the offset from the first context detail of the actual context
+      # detail to be substituted (i.e. 0 is the first context detail).
+      #
+      # ==== Parameters
+      # text::  The input string that will be populated.
+      #
+      def populate(text)
+         message = text
+         @context.each_index do |index|
+            expr = Regexp.new("\\{#{index}\\}")
+            message.gsub!(expr, @context[index].to_s)
+         end
+         message
+      end
+   end # End of the IotazError class.
+end # End of the Iotaz module.

data/lib/iotaz/MetaData.rb

@@ -0,0 +1,646 @@
+#!/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 'stringio'
+
+module Iotaz
+   #
+   # This class represents the definition of the meta-data for a class attribute
+   # and is used by the IotazMetaData class.
+   #
+   class Attribute
+      #
+      # This is the construct for thte Attribute class.
+      #
+      # ==== Parameters
+      # name::    The name of the class attribute.
+      # column::  The name of the database column that the attribute will be
+      #           stored in. This defaults to nil to indicate that the database
+      #           column name mirrors the attribute name.
+      # type::    An indicator of the type that is expected for the column
+      #           value. This defaults to nil to indicate that the type will
+      #           be deduced automatically.
+      #
+      def initialize(name, column=nil, type=nil)
+         @name     = name
+         @column   = column == nil ? name : column
+         @type     = type
+         @accessor = name
+         @mutator  = "#{name}="
+      end
+
+
+      #
+      # Attribute accessor to indicate whether the attribute is a generated
+      # value. Always returns false.
+      #
+      def is_generated?
+         false
+      end
+      
+      
+      #
+      # This method invokes the accessor for an attribute against a specified
+      # object, returning the result.
+      #
+      # ==== Parameters
+      # object::  The object to invoked the accessor for.
+      #
+      def get(object)
+         object.__send__("#{@accessor}".intern)
+      end
+      
+      
+      #
+      # This method invokes the mutator for an attribute against a specified
+      # object.
+      #
+      # ==== Parameters
+      # object::  The object to invoked the muator for.
+      # value::   The value to be passed as a parameter to the mutator.
+      #
+      def set(object, value)
+         object.__send__("#{@mutator}".intern, value)
+      end
+      
+      
+      #
+      # This method provides a textual description for an Attribute object.
+      #
+      # ==== Parameters
+      # indent::  The number of spaces to prefix to the lines of the string
+      #           generated by the method. Defaults to zero.
+      #
+      def to_s(indent=0)
+         prefix = indent > 0 ? ' ' * indent : ''
+         text   = StringIO.new
+         text << prefix << "Attribute:\n" << prefix << "   Name: #{@name}, "
+         text << "Column: #{@column}, Type: #{@type}\n" << prefix << '   '
+         text << "Accessor: #{@accessor}, Mutator: #{@mutator}"
+         text.string
+      end
+      
+      
+      #
+      # This method overloads the equivalence test operator for the Attribute
+      # class.
+      #
+      # ==== Parameters
+      # object::  A reference to the object to be compared with.
+      #
+      def ==(object)
+         result = false
+         if object.kind_of?(Attribute)
+            result = (@name     == object.name and
+                      @column   == object.column and
+                      @type     == object.type and
+                      @accessor == object.accessor and
+                      @mutator  == object.mutator)
+         end
+         result
+      end
+
+
+      # Class attribute accessor.
+      attr_reader :name, :column, :type, :accessor, :mutator
+      
+      # Class attribute mutator.
+      attr_writer :name, :column, :type, :accessor, :mutator
+   end # End of the Attribute class.
+   
+   
+   #
+   # This class represents a value that is automatically generated by the
+   # library as opposed to actually being set within the object.
+   #
+   class GeneratedAttribute < Attribute
+      #
+      # This is the constructor for the the GeneratedAttribute class.
+      #
+      # ==== Parameters
+      # name::    The name of the class attribute.
+      # type::    An indicator of the type that is expected for the column
+      #           value. This should be one of 'SEQUENCE', 'DATE', 'TIME' or
+      #           'TIMESTAMP'.
+      # events::  This parameter indicates what events will cause the value to
+      #           be generated. This should be one of 'INSERT', 'UPDATE' or
+      #           'INSERT,UPDATE'.
+      # source::  A type related value that provides additional information
+      #           for use in generating the value. For sequences this should be
+      #           the name of the sequence. For dates this should be one of
+      #           'YESTERDAY', 'TODAY' or 'TOMORROW'. For time and timestamp
+      #           values 'NOW' is the only supported value.
+      # column::  The name of the database column that the attribute will be
+      #           stored in. This defaults to nil to indicate that the database
+      #           column name mirrors the attribute name.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever an invalid type, events or source value
+      #               is specified.
+      #
+      def initialize(name, type, events, source, column=nil)
+         super(name, column, type.strip.upcase)
+         @events = events.gsub(/\s+/, '').upcase
+         @source = source
+         
+         # Validate the parameters.
+         types = ['SEQUENCE', 'TIME', 'DATE', 'TIMESTAMP']
+         if types.include?(type.strip.upcase) == false
+            raise IotazError.new("'{0}' is not a valid type for a generated "\
+                                 "attribute. Acceptable values are {1}.",
+                                 type, types.join(",'"))
+         end
+         
+         occurs = ['INSERT', 'UPDATE', 'INSERT,UPDATE', 'UPDATE,INSERT']
+         if occurs.include?(@events) == false
+            raise IotazError.new("'{0}' is not a valid event set for the "\
+                                 "{1} generated attribute. Valid settings "\
+                                 "are {1}.", events, name,
+                                 occurs[1,3].join(', '))
+         end
+         
+         if type == 'SEQUENCE'
+            if source == nil or source.length == 0
+               raise IotazError.new("Sequence name not specified for the {0} "\
+                                    "generated attribute.", name)
+            end
+         elsif type == 'DATE'
+            values = ['YESTERDAY', 'TODAY', 'TOMORROW']
+            if values.include?(source.upcase) == false
+               raise IotazError.new("Invalid generation source specified for "\
+                                    "the {0} generated attribute. Valid "\
+                                    "settings are {1}.", name, values.join(', '))
+            end
+            @source = @source.upcase
+         else
+            if source.upcase != "NOW"
+               raise IotazError.new("Invalid generation source specified for "\
+                                    "the {0} generated attribute. Valid setting "\
+                                    "is {1}.", name, 'NOW')
+            end
+         end
+      end
+      
+      
+      #
+      # This method is the mutator for the events attribute, policing the values
+      # specified to the object.
+      #
+      # ==== Parameters
+      # setting::  A string containing the new events setting for the object.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever an invalid events setting is specified.
+      #
+      def events=(setting)
+         value  = setting.gsub(/\s+/, '').upcase
+         occurs = ['INSERT', 'UPDATE', 'INSERT,UPDATE', 'UPDATE,INSERT']
+         if occurs.include?(value) == false
+            raise IotazError.new("'{0}' is not a valid event set for the "\
+                                 "{1} generated attribute. Valid settings "\
+                                 "are {1}.", setting, name,
+                                 occurs[1,3].join(', '))
+         end
+         @events = value
+      end
+      
+      
+      #
+      # This method is the mutator for the source attribute, policing the values
+      # specified to the object.
+      #
+      # ==== Parameters
+      # source::  A string containing the objects new source setting.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever the source specified is not valid for
+      #               the type.
+      #
+      def source=(source)
+         if type == 'SEQUENCE'
+            if source == nil or source.length == 0
+               raise IotazError.new("Sequence name not specified for the {0} "\
+                                    "generated attribute.", name)
+            end
+         elsif type == 'DATE'
+            values = ['YESTERDAY', 'TODAY', 'TOMORROW']
+            if values.include?(source.upcase) == false
+               raise IotazError.new("Invalid generation source specified for "\
+                                    "the {0} generated attribute. Valid "\
+                                  "settings are {1}.", name, values.join(', '))
+            end
+         else
+            if source.upcase != "NOW"
+               raise IotazError.new("Invalid generation source specified for "\
+                                    "the {0} generated attribute. Valid setting "\
+                                  "is {1}.", name, 'NOW')
+            end
+         end
+         @source = source
+      end
+      
+      
+      #
+      # This method is the mutator for the type attribute, policing the values
+      # specified to the object.
+      #
+      # ==== Parameters
+      # setting::  A string containing the new type setting for the object.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever an invalid type setting is specified.
+      #
+      def type=(setting)
+         value = setting.strip.upcase
+         types = ['SEQUENCE', 'TIME', 'DATE', 'TIMESTAMP']
+         if types.include?(type.upcase) == false
+            raise IotazError.new("'{0}' is not a valid type for a generated "\
+                                 "attribute. Acceptable values are {1}.",
+                               type, types.join(",'"))
+         end
+         super(value)
+      end
+
+
+      #
+      # Attribute accessor to indicate whether the attribute is a generated
+      # value. Always returns true.
+      #
+      def is_generated?
+         true
+      end
+
+
+      #
+      # This method overloads the equivalence test operator for the
+      # GeneratedAttribute class.
+      #
+      # ==== Parameters
+      # object::  A reference to the object to be compared with.
+      #
+      def ==(object)
+         result = false
+         if object.instance_of?(GeneratedAttribute)
+            result = super(object)
+            if result
+               result = (@events == object.events and @source  == object.source)
+            end
+         end
+         result
+      end
+      
+      
+      #
+      # This method generates a textual description for a GeneratedAttribute
+      # object.
+      #
+      # ==== Parameters
+      # indent::  The number of spaces to prefix to the lines of the string
+      #           generated by the method. Defaults to zero.
+      #
+      def to_s(indent=0)
+         prefix = indent > 0 ? ' ' * indent : ''
+         text   = StringIO.new
+         text << super(indent) << "\n" << prefix << "   Events: #{@events}, "
+         text << "Source: #{@source}"
+         text.string.gsub(/Attribute:/, 'Generated Attribute:')
+      end
+      
+      
+      # Class attribute accessor.
+      attr_reader :events, :source
+   end # End of the GeneratedAttribute class.
+   
+   
+   #
+   # This class represents the meta-data for a class that can be used in
+   # persisting instances of the class. Basically this class hold the details
+   # of what is to be stored, where it is to be stored, how the specified
+   # values can be accessed or updated and whether the value is automatically
+   # generated.
+   #
+   class IotazMetaData
+      # Includes.
+      include Enumerable
+      
+      
+      #
+      # This is the constructor for the IotazMetaData class.
+      #
+      # ==== Parameters
+      # klass::  Eiher class that the meta-data will relate to or a string
+      #          containing the class name.
+      # table::  The name of the database table that the class data will be
+      #          fed into. This defaults to nil to indicate that the table
+      #          name is the same as the class name.
+      #
+      def initialize(klass, table=nil)
+         terse       = IotazMetaData.get_class_name(klass)
+         @klass      = klass.class == Class ? klass : Kernel.const_get(klass)
+         @name       = klass.instance_of?(String) ? klass : klass.name
+         @table      = table == nil ? terse : table
+         @attributes = Hash.new
+         @keys       = Array.new
+      end
+      
+      
+      #
+      # This method adds an attribute to the list maintained by an instance of
+      # the IotazMetaData class.
+      #
+      # ==== Parameters
+      # attribute::  A reference to an Attribute object containing the details
+      #              of the new attribute.
+      # key::        A boolean flag to indicate whether the field is part of
+      #              the key for the record. This defaults to false.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated if the attribute name clashes with an existing
+      #               meta-data attribute or the Attribute object specifies a
+      #               column that has already been specified by another attribute.
+      #
+      def add_attribute(attribute, key=false)
+         if @attributes.key?(attribute.name)
+            raise IotazError.new("The meta-data for the {0} class already "\
+                                 "possesses an attribute called {1}.",
+                                 @name, attribute.name)
+         end
+         
+         match = @attributes.find {|entry| entry[1].column == attribute.column}
+         if match != nil
+            raise IotazError.new("The {0} meta-data attribute of the {1} class "\
+                                 "is specified for the {2} database column. The "\
+                                 "{3} attribute also specifies this column.",
+                                 attribute.name, @name, attribute.column,
+                                 match.name)
+         end
+         @attributes[attribute.name] = attribute
+         @keys.push(attribute.name) if key
+      end
+      
+      
+      #
+      # This method fetches an attribute definition from a IotazMetaData class
+      # instance. If the requested attribute does not exist then the method
+      # returns nil.
+      #
+      # ==== Parameters
+      # name::  The name of the attribute to be fetched.
+      #
+      def get_attribute(name)
+         @attributes[name]
+      end
+      
+      
+      #
+      # This method fetches an attribute from the MetaData object based on the
+      # attribute column name. The column name comparison is case insensitive.
+      #
+      # ==== Parameters
+      # column::  The name of the column to fetch the attribute for.
+      #
+      def get_attribute_for_column(column)
+         @attributes.values.find do |attribute|
+            attribute.column.upcase == column.upcase
+         end
+      end
+      
+      
+      #
+      # This method removes an attribute definition from a IotazMetaData class
+      # instance. If the specified attribute does not exist then the method
+      # does nothing.
+      #
+      # ==== Parameters
+      # name::  The name of the attribute to be removed.
+      #
+      def delete_attribute(name)
+         @attributes.delete(name) if @attributes.key?(name)
+         @keys.delete_if {|entry| entry == name}
+      end
+      
+      
+      #
+      # This method fetches an array containing the value for the key attributes
+      # for a given object.
+      #
+      # ==== Parameters
+      # object::  A reference to the object to fetch the key values for.
+      #
+      def get_key_values(object)
+         values = []
+         @keys.each do |key|
+            values.push(@attributes[key].get(object))
+         end
+         values
+      end
+      
+      
+      #
+      # This method provides for iteration over the attribute contents of a
+      # IotazMetaData object.
+      #
+      def each
+         result = nil
+         if block_given?
+            @attributes.each do |name, attribute|
+               result = yield attribute
+            end
+         end
+         result
+      end
+      
+      
+      #
+      # This method is used to determine whether a specified attribute exists
+      # within a IotazMetaData object.
+      #
+      # ==== Parameters
+      # name::  The name of the attribute to check for.
+      #
+      def attribute_exists?(name)
+         @attributes.key?(name)
+      end
+      
+      
+      #
+      # This method takes a QueryRow record and transforms it into an instance
+      # of the class associated with the IotazMetaData instance.
+      #
+      # ==== Parameters
+      # row::  A reference to a QueryRow object containing the data that will
+      #        be used in creating the object.
+      #
+      # ==== Exceptions
+      # IotazMetaData::  Generated whenever the row data doesn't contain all
+      #                  the required object fields.
+      #
+      def to_object(row)
+         populate(@klass.allocate, row)
+      end
+      
+      
+      #
+      # This method populates an object with a specified set of values.
+      #
+      # ==== Parameters
+      # object::  A reference to the object to be populated.
+      # data::    A hash containing a mapping between attribute column names and
+      #           the values for the attributes.
+      #
+      def populate(object, data)
+         data.each do |name, value|
+            get_attribute_for_column(name).set(object, value)
+         end
+         object
+      end
+
+      
+      #
+      # This method retrieves a textual description for a IotazMetaData object.
+      #
+      # ==== Parameters
+      # indent::  The number of spaces to prefix to the lines generated by the
+      #           method. Defaults to zero.
+      #
+      def to_s(indent=0)
+         prefix = indent > 0 ? ' ' * indent : ''
+         text   = StringIO.new
+         text << prefix << "Iotaz Meta Data:\n" << prefix << "   Class: "
+         text << "#{@name}, Table: #{@table}, Keys: #{@keys.join(', ')}"
+         @attributes.each do |name, attribute|
+            text << "\n" << attribute.to_s(indent + 3)
+         end
+         text.string
+      end
+      
+      
+      #
+      # This method is used to determine the table name for the meta-data.
+      #
+      # ==== Parameters
+      # klass::  A reference to the class that the meta-data will represent.
+      #
+      def IotazMetaData.get_class_name(klass)
+         name  = klass.name
+         index = klass.name.rindex('::')
+         if index != nil
+            index = index + 2
+            name  = name[index, name.length - index]
+         end
+         name
+      end
+      
+      
+      #
+      # This method takes a class and scans it to automatically generate a
+      # meta-data profile for the class. The scanning follows some simple
+      # rules
+      #  - An attribute that can be persisted is considered to exist within
+      #    the class if methods called {name}/is_{name}/is_{name}? and {name}=
+      #    exist within the class (i.e. an accessor and mutator can be located
+      #    for the attribute).
+      #  - If the class possesses an attribute called id or {lower case class
+      #    name}_id then this will be considered a generated attribute based on
+      #    a sequence. The name of the sequence to be used will be the attribute
+      #    name, converted to upper case, suffixed with '_ID_SQ'. The attribute
+      #    will also be set as the key for the meta-data object.
+      #  - If the class possesses attributes called created or updated then
+      #    these will be considered generated values. The created attribute
+      #    will be assigned a value for insertion and never altered. The
+      #    update attribute will be assigned values for updates.
+      #
+      # ==== Parameters
+      # klass::  A reference to the class to be scanned.
+      #
+      def IotazMetaData.scan(klass)
+         terse = IotazMetaData.get_class_name(klass)
+         
+         # Create a list of all class methods.
+         all = klass.public_instance_methods
+         all.concat(klass.protected_instance_methods)
+         all.concat(klass.private_instance_methods)
+         
+         # Locate mutators.
+         mutators = all.collect do |entry|
+            if ['==', '==='].include?(entry) == false and entry[-1,1] == "="
+               entry
+            else
+               nil
+            end
+         end
+         mutators.compact!
+         
+         # Compile a list of attribute names, accessors and mutators.
+         methods = Array.new
+         mutators.each do |entry|
+            name = entry.chop
+            if all.include?(name)
+               methods.push([name, name, entry])
+            elsif all.include("is_#{name}")
+               methods.push([name, "is_#{name}", entry])
+            elsif all.include("is_#{name}?")
+               methods.push([name, "is_#{name}?", entry])
+            end
+         end
+         
+         result = IotazMetaData.new(klass)
+         methods.each do |entry|
+            attribute = nil
+            key       = false
+            if entry[0] == 'id' or entry == "#{klass.name.downcase}_id"
+               attribute = GeneratedAttribute.new(entry[0], 'SEQUENCE',
+                                                  'INSERT',
+                                                  "#{terse}_ID_SQ")
+                                                   
+               attribute.accessor = entry[1]
+               attribute.mutator  = entry[2]
+               key                = true
+            elsif entry[0] == 'created'
+               attribute = GeneratedAttribute.new(entry[0], 'TIMESTAMP',
+                                                  'INSERT', 'NOW')
+               attribute.accessor = entry[1]
+               attribute.mutator  = entry[2]
+            elsif entry[0] == 'updated'
+               attribute = GeneratedAttribute.new(entry[0], 'TIMESTAMP',
+                                                  'UPDATE', 'NOW')
+               attribute.accessor = entry[1]
+               attribute.mutator  = entry[2]
+            else
+               attribute = Attribute.new(entry[0])
+               attribute.accessor = entry[1]
+               attribute.mutator  = entry[2]
+            end
+            result.add_attribute(attribute, key)
+         end
+         result
+      end
+      
+      
+      # Class attribute accessor.
+      attr_reader :klass, :name, :table, :keys
+      
+      # Class attribute mutator.
+      attr_writer :table
+   end # End of the IotazMetaData class.
+end # End of the Iotaz module.