iotaz 0.1.0

data/lib/iotaz/Query.rb

@@ -0,0 +1,566 @@
+#!/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 specific language 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 'stringio'
+require 'iotaz/IotazError'
+
+module Iotaz
+   #
+   # This class represents a field that constitutes a component within a Query
+   # object.
+   #
+   class QueryField
+      #
+      # This is a constructor for the QueryField class.
+      #
+      # ==== Parameters
+      # name::      A string containing the name of the attribute to be made
+      #             into a QueryField
+      # metadata::  A reference to the class IotazMetaData object that contains
+      #             the attribute details.
+      # fetched::   A boolean flag to indicate whether the field should be
+      #             part of the list of values fetched. This defaults to true.
+      #
+      def initialize(name, metadata, fetched=true)
+         @name       = name
+         @metadata   = metadata
+         @fetched    = fetched
+         @comparison = nil
+         @value      = nil
+         if @metadata.get_attribute(name) == nil
+            raise IotazError.new("'{0}' is not an attribute of the {1} class "\
+                                 "and therefore cannot be used to create "\
+                                 "query field.", name, metadata.name)
+         end
+      end
+      
+      
+      #
+      # Attribute accessor that fetches the column name for a QueryField.
+      #
+      def column
+         @metadata.get_attribute(@name).column
+      end
+      
+      
+      #
+      # Attribute accessor that fetches the column table name for a QueryField.
+      #
+      def table
+         @metadata.table
+      end
+      
+      
+      #
+      # This method attempts to perform a field name match for a QueryField
+      # object. A name matches a QueryField name if the name provided...
+      #
+      #  - Matches the name of the underlying attribute.
+      #
+      #  - Matches the name of the underlying attribute qualified by its class
+      #    name.
+      #
+      #  - Matches the name fo the underlying attributes column name.
+      #
+      #  - Matches the name for the underlying attributes column name qualified
+      #    with it's table name.
+      #
+      def name_match?(name)
+         attribute = @metadata.get_attribute(@name)
+         @name == name or
+         "#{@metadata.name}.#{@name}" == name or
+         "#{attribute.column}" == name or
+         "#{@metadata.table}.#{attribute.column}" == name
+      end
+
+
+      #
+      # This method sets a query field for a straight equivalence comaparison
+      # to another value. If the value passed to this method is nil then this
+      # changes the comparison to an is null check.
+      #
+      # ==== Parameters
+      # value::  The value to compare the field to.
+      #
+      def equal_to(value)
+         @comparison = value == nil ? 'is null' : '= ?'
+         @value      = value
+      end
+
+
+      #
+      # This method sets a query field for a straight non-equivalence
+      # comaparison to another value. If the value passed to this method is nil
+      # then this changes the comparison to an is not null check.
+      #
+      # ==== Parameters
+      # value::  The value to compare the field to.
+      #
+      def not_equal_to(value)
+         @comparison = value == nil ? 'is not null' : '!= ?'
+         @value      = value
+      end
+
+
+      #
+      # This method sets a query feld for a greater than comparison to another
+      # value.
+      #
+      # ==== Parameters
+      # value::  The value to perform the comparison against. This must not be
+      #          nil.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever a nil value is specified to the method.
+      #
+      def greater_than(value)
+         if value == nil
+            raise IotazError.new("Nil value specified for greater than "\
+                                 "comparison on the {0} query field.",
+                                 @attribute.name)
+         end
+         @comparison = '> ?'
+         @value      = value
+      end
+
+
+      #
+      # This method sets a query feld for a less than comparison to another
+      # value.
+      #
+      # ==== Parameters
+      # value::  The value to perform the comparison against. This must not be
+      #          nil.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever a nil value is specified to the method.
+      #
+      def less_than(value)
+         if value == nil
+            raise IotazError.new("Nil value specified for less than "\
+                                 "comparison on the {0} query field.",
+                                 @attribute.name)
+         end
+         @comparison = '< ?'
+         @value      = value
+      end
+
+
+      #
+      # This method sets a query feld for a greater than comparison to another
+      # value.
+      #
+      # ==== Parameters
+      # value::  The value to perform the comparison against. This must not be
+      #          nil.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever a nil value is specified to the method.
+      #
+      def greater_than_or_equal_to(value)
+         if value == nil
+            raise IotazError.new("Nil value specified for greater than or "\
+                                 "equal to comparison on the {0} query field.",
+                                 @attribute.name)
+         end
+         @comparison = '>= ?'
+         @value      = value
+      end
+
+
+      #
+      # This method sets a query feld for a less than comparison to another
+      # value.
+      #
+      # ==== Parameters
+      # value::  The value to perform the comparison against. This must not be
+      #          nil.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever a nil value is specified to the method.
+      #
+      def less_than_or_equal_to(value)
+         if value == nil
+            raise IotazError.new("Nil value specified for less than or equal"\
+                                 "to comparison on the {0} query field.",
+                                 @attribute.name)
+         end
+         @comparison = '<= ?'
+         @value      = value
+      end
+
+
+      #
+      # This method sets a query for a between comparison to two other values.
+      #
+      # ==== Parameters
+      # lower::  A reference to the value that represents the upper edge of the
+      #          comparison. This value must not be nil.
+      # upper::  A reference to the value that represents the upper edge of the
+      #          comparison. This value must not be nil.
+      #
+      def between(lower, upper)
+         if lower == nil or upper == nil
+            raise IotazError.new("Nil value specified for between comparison "\
+                                 "on the {0} query field.", @attribute.name)
+         end
+         @comparison = 'between ? and ?'
+         @value      = [lower, upper]
+      end
+
+
+      #
+      # This method sets a query for a not between comparison to two other
+      # values.
+      #
+      # ==== Parameters
+      # lower::  A reference to the value that represents the upper edge of the
+      #          comparison. This value must not be nil.
+      # upper::  A reference to the value that represents the upper edge of the
+      #          comparison. This value must not be nil.
+      #
+      def not_between(lower, upper)
+         if lower == nil or upper == nil
+            raise IotazError.new("Nil value specified for not between "\
+                                 "comparison on the {0} query field.",
+                                 @attribute.name)
+         end
+         @comparison = 'not between ? and ?'
+         @value      = [lower, upper]
+      end
+
+
+      #
+      # This method sets a query for an in comparison to a set of values.
+      #
+      # ==== Parameters
+      # values::  An array containing the full set of values to be compared
+      #           with. This may not be empty.
+      #
+      def in(*values)
+         if values.size == 0
+            raise IotazError.new("Empty values set specified for in "\
+                                 "comparison on the {0} query field.",
+                                 @attribute.name)
+         end
+         
+         list = []
+         values.each do |entry|
+            text = entry.class == String ? "'#{entry}'" : entry
+            list.push(text)
+         end
+         
+         @comparison = "in (#{list.join(', ')})"
+         @value      = nil
+      end
+
+
+      #
+      # This method sets a query for a not in comparison to a set of values.
+      #
+      # ==== Parameters
+      # values::  An array containing the full set of values to be compared
+      #           with. This may not be empty.
+      #
+      def not_in(*values)
+         if values.size == 0
+            raise IotazError.new("Empty values set specified for not in "\
+                                 "comparison on the {0} query field.",
+                                 @attribute.name)
+         end
+         
+         list = []
+         values.each do |entry|
+            text = entry.class == String ? "'#{entry}'" : entry
+            list.push(text)
+         end
+         
+         @comparison = "not in (#{list.join(', ')})"
+         @value      = nil
+      end
+      
+      
+      # Attribute accessor.
+      attr_reader :name, :fetched, :comparison, :value
+      
+      # Attribute mutator.
+      attr_writer :fetched
+      
+      # Method aliases.
+      alias :fetched? :fetched
+   end # Endo of the QueryField class.
+   
+   
+   #
+   # This class models a SQL query against one or more database tables.
+   #
+   class Query
+      #
+      # This is the constructor for the Query class.
+      #
+      # ==== Parameters
+      # klass::   A reference to a Class object representing the first table
+      #           element of the query.
+      # fields::  A array of the name of class attributes that are to be
+      #           included in the results for the query. If this is empty
+      #           then all fields are marked as fetched.
+      #
+      def initialize(klass, *fields)
+         # Initialise instances values.
+         @definitions = []
+         @fields      = []
+         
+         # Process the class attributes as fields.
+         @definitions.push(klass.iotaz_meta_data)
+         @definitions[0].each do |attribute|
+            flag = fields.size > 0 ? fields.include?(attribute.name) : true
+            @fields.push(QueryField.new(attribute.name, @definitions[0], flag))
+         end
+      end
+      
+      
+      #
+      # This method retrieves a reference to a QueryField object within a
+      # Query instance. Fields my be referenced in a number of ways. They can
+      # be referenced by their attribute name, they can be referenced to their
+      # attribute name qualified by a class name, they can be referenced by
+      # their column name or they can be referenced by their column name
+      # qualified by their table name. The method returns nil if the specified
+      # field does not exist.
+      #
+      # ==== Parameters
+      # name::  The name of the field to be retrieved.
+      #
+      # ==== Exceptions
+      # IotazError::  Generated whenever the field name specified is ambiguous
+      #               and can potential refer to multiple fields.
+      #
+      def field(name)
+         field = get_fields(name)
+         if field.class == Array
+            raise IotazError.new("Ambiguous field name. The name '{0}' cannot "\
+                                 "be resolved to a unique field.", name)
+         end
+         field
+      end
+      
+      
+      #
+      # This method generates the SQL statement for a Query object and assembles
+      # the list of parameters that will be needed to execute it. The method
+      # returns two elements, a string containing the SQL and an array
+      # containing the parameters.
+      #
+      def to_sql
+         parameters = []
+         select     = StringIO.new
+         from       = StringIO.new
+         where      = StringIO.new
+         
+         fields     = 0
+         tables     = []
+         clauses    = 0
+         
+         select << 'select '
+         from   << ' from '
+         where  << ' where '
+         
+         @fields.each do |field|
+            # Check if the field is retrieved.
+            if field.fetched?
+               select << ', ' if fields > 0
+               select << field.column
+               fields += 1
+            end
+            
+            # Check if the fields table has already been added,
+            pattern = Regexp.new(field.table)
+            if tables.include?(field.table) == false
+               from << ", " if tables.size > 0
+               from << field.table
+               tables.push(field.table)
+            end
+            
+            # Check if the field has a comparison.
+            if field.comparison != nil
+               where << ' and ' if clauses > 0
+               where << field.column << ' ' << field.comparison
+               if field.value.class == Array
+                  parameters = parameters.concat(field.value)
+               else
+                  parameters.push(field.value) if field.value != nil
+               end
+               clauses += 1
+            end
+         end
+         
+         # Generate the SQL statement.
+         sql = select.string + from.string
+         sql += where.string if clauses > 0
+         
+         [sql, parameters]
+      end
+      
+      
+      #
+      # This method is used for field name matching. The method will return
+      # one of three possible values. If a specified name uniquely matches a
+      # field within the Query object then this will be returned. If it matches
+      # more than one field then an array of fields will be returned. If it
+      # matches not fields then nil will be returned.
+      #
+      # ==== Parameters
+      # name::  A reference to the name of the field to be retrieved. See the
+      #         description for the field method for details of the values that
+      #         are accepted for this parameter.
+      #
+      def get_fields(name)
+         result = nil
+         
+         matches = @fields.collect do |field|
+            field.name_match?(name) ? field : nil
+         end
+         matches.compact!
+         
+         if matches.size > 0
+            result = matches.size == 1 ? matches[0] : matches
+         end
+         
+         result
+      end
+      
+      
+      # Method access alterations.
+      private :get_fields
+   end # End of the Query class.
+   
+   
+   #
+   # This class models a row of data returned from the execution of a query.
+   # The class provides a mapping between the (case insensitive) column names
+   # and the column values for the row.
+   #
+   class QueryRow
+      #
+      # This is the constructor for the QueryRow class.
+      #
+      def initialize
+         @entries = Hash.new
+      end
+      
+      #
+      # This method fetches a count of the number of columns within a QueryRow
+      # object.
+      #
+      def size
+         @entries.size
+      end
+      
+      
+      #
+      # This method test whether a given column name exists within a QueryRow
+      # object.
+      #
+      # ==== Parameters
+      # name::  The name of the column to check for.
+      #
+      def exists?(name)
+         @entries.key?(name.upcase)
+      end
+      
+      
+      #
+      # This method fetches an array of the column names for a QueryRow object.
+      #
+      def columns
+         @entries.keys
+      end
+      
+      
+      #
+      # This method fetches an array of the column values for a QueryRow object.
+      #
+      def values
+         @entries.values
+      end
+      
+      
+      #
+      # This method provides an iterator for the contents of a QueryRow object.
+      # The block passed to this method should take two parameters. The first
+      # will be the column name and the second will be the column value.
+      #
+      def each
+         if block_given?
+            @entries.each {|name, value| yield(name, value)}
+         end
+      end
+      
+      
+      #
+      # This method adds or updates a new column value to a QueryRow object.
+      # Note that the column names used by this class are case insensitive so
+      # 'COLUMN' is the same as 'Column', 'column' or 'cOLumn'.
+      #
+      # ==== Parameters
+      # name::   A reference to the column name to be stored or updated.
+      # value::  A reference to the column value to be stored.
+      #
+      def []=(name, value)
+         @entries[name.upcase] = value
+      end
+      
+      
+      #
+      # This method fetches the value for a specified column. If the specified
+      # column does not exist then an exception is thrown.
+      #
+      # ==== Parameters
+      # name::  A reference to a string containing the name of the column to
+      #         fetch the value for.
+      #
+      # ==== Exception
+      # IotazError::  Generated whenever the column name specified does not
+      #               exist within the QueryRow object.
+      #
+      def [](name)
+         if @entries.key?(name.upcase) == false
+            raise IotazError.new("Column not found. A '{0}' column does not "\
+                                 "exist in the query row data.", name)
+         end
+         @entries[name.upcase]
+      end
+      
+      
+      #
+      # This method provides a string description for a QueryRow object.
+      #
+      def to_s
+         out = StringIO.new
+         @entries.each do |column, value|
+            out << ', ' if out.string.length > 0
+            out << "#{column} = #{value}"
+         end
+         out.string
+      end
+   end # End of the QueryRow class.
+end # End of the Iotaz module.