doeskeyvalue 0.2.2 → 0.9.0

data/lib/doeskeyvalue.rb

@@ -1,100 +1,67 @@
 # AWEXOME LABS
 # DoesKeyValue
 
-require 'doeskeyvalue'
-require 'rails'
-require 'active_record'
-require 'hashie'
-
-require 'doeskeyvalue/key_manager'
-require 'doeskeyvalue/keys'
-require 'doeskeyvalue/indexes'
-require 'doeskeyvalue/util'
+require "doeskeyvalue"
+require "active_record"
+require "active_support"
+require "hashie"
 
+require "doeskeyvalue/configuration"
+require "doeskeyvalue/state"
+require "doeskeyvalue/util"
+require "doeskeyvalue/index"
+require "doeskeyvalue/accessors"
+# require "doeskeyvalue/column_storage"   # <= Deprecating in favor of combined Accessors
+# require "doeskeyvalue/table_storage"    # <= Deprecating in favor of combined Accessors
 
 module DoesKeyValue
 
-  # Create a Rails Engine
-  class Engine < Rails::Engine
-  end
-  
   # Return the current working version from VERSION file:
   def self.version
-    @@version ||= File.open(File.join(File.dirname(__FILE__), "..", "VERSION"), "r").read
-  end
-  
-  # Exception Types for DoesKeyValue
-  class NoColumnNameSpecified < Exception
-    def initialize(msg="A class column name must be provided for storing key values in blob"); super(msg); end
-  end
-  class NoKeyNameSpecified < Exception
-    def initialize(msg="A key name must be provided to build a DoesKeyValue key"); super(msg); end
+    Gem.loaded_specs["doeskeyvalue"].version.to_s
   end
-  class NoKeyForThatIndex < Exception
-    def initialize(msg="A key must exist before an index can be applied to it"); super(msg); end
-  end
-  class KeyAndIndexOptionsMustBeHash < Exception
-    def initialize(msg="Options passed to declarations of keys and indexes must of class Hash"); super(msg); end
-  end
-  class KeyValueIndexTableDoesNotExist < Exception
-    def initialize(msg="DoesKeyValue requires an index table be generated to use key indexes. Use generator to generate migration"); super(msg); end
+
+  # Log messages
+  def self.log(msg)
+    puts "DoesKeyValue: #{msg}" unless configuration.log_level == :silent
   end
-  
+    
 end # DoesKeyValue
 
 
 module ActiveRecord
   class Base
-    
-    # Call this method within your class to establish key-value behavior and prep
-    # the internal structure that will hold the blob
-    def self.doeskeyvalue(column, opts={})
+
+    # Call this "acts as" method within your ActiveRecord class to establish key-
+    # value behavior and prepare internal storage structures
+    def self.does_keys(opts={})
+      DoesKeyValue.log("Adding key-value support to class #{self.to_s}")
+      # TODO: Raise exception to improper opts passed
       self.instance_eval do
-        extend DoesKeyValue::Keys
-        extend DoesKeyValue::Indexes
-        
-        # Identify the AR text column holding our data and serialize it:
-        @column_name = column.to_sym
-        cattr_accessor :column_name
-        serialize @column_name, Hashie::Mash
-        
-        # Add the column to the key and column manager so we can reference it later:
-        DoesKeyValue::KeyManager.instance.declare_column(self, @column_name)
+        DoesKeyValue::State.instance.add_class(self, opts)
+        self.send(:serialize, opts[:column], Hash) if opts[:column]
+        self.send(:attr_accessor, :key_value_cache) if opts[:table]
+        extend DoesKeyValue::Accessors
       end
-      
-      Array.class_eval do
-        include DoesKeyValue::Util::CondArray
-      end
-      
-      instance_eval <<-EOS
-        def #{@column_name}_key(key_name, opts={})
-          column_name = :#{@column_name}
-          key_name = key_name.to_sym
-          declare_key(column_name, key_name, opts)
-        end
-        
-        def #{@column_name}_index(key_name, opts={})
-          column_name = :#{@column_name}
-          key_name = key_name.to_sym
-          declare_index(column_name, key_name, opts)
-        end
-        
-        def key_value_columns
-          return DoesKeyValue::KeyManager.instance.columns_for(self)
-        end
-                  
-        def #{@column_name}_keys
-          column_name = :#{@column_name}
-          return DoesKeyValue::KeyManager.instance.keys_for(self, column_name)
-        end
-        
-        def #{@column_name}_indexes
-          column_name = :#{@column_name}
-          return DoesKeyValue::KeyManager.instance.indexes_for(self, column_name)
-        end
-      EOS
+
+
+      # if storage_column = opts[:column]
+      #   DoesKeyValue.log("Adding key-value support via column #{storage_column} to class #{self.to_s}")
+      #   self.instance_eval do
+      #     DoesKeyValue::State.instance.add_class(self, :column=>storage_column)
+      #     self.send(:serialize, storage_column, Hash)
+      #     extend DoesKeyValue::ColumnStorage
+      #   end
+
+      # elsif storage_table = opts[:table]
+      #   DoesKeyValue.log("Adding key-value support via table #{storage_table} to class #{self.to_s}")
+      #   self.instance_eval do
+      #     DoesKeyValue::State.instance.add_class(self, :table=>storage_table)
+      #     extend DoesKeyValue::TableStorage
+      #   end
+      # end
+
     end
     
-    
-  end # ActiveRecord::Base
+  end # Base
 end # ActiveRecord

data/lib/doeskeyvalue/accessors.rb

@@ -0,0 +1,136 @@
+# AWEXOME LABS
+# DoesKeyValue
+#
+# TableStorage -- Accessor and update methods for keys managed under the
+#  key-value store defined for given classes.
+
+module DoesKeyValue
+
+  # Define our types for strongly-typed results storage:
+  SUPPORTED_DATA_TYPES = %w(string integer decimal boolean datetime)
+
+  module Accessors
+
+    # Define a supported key
+    def has_key(key_name, opts={})
+      opts = {
+        index: true,
+        type: "string",
+        default: nil
+      }.merge(opts)
+
+      # Table-based storage dictates an index:
+      opts[:index] = true if table_storage?
+
+      # Cache values of common options:
+      key_indexed = opts[:index]
+      key_type = opts[:type].to_sym
+      key_default_value = opts[:default]
+
+      # Ensure we are invoked with a supported data type:
+      raise Exception.new("Data type not supported: #{key_type}") unless DoesKeyValue::SUPPORTED_DATA_TYPES.include?(key_type.to_s)
+
+      # Save a representation of this key in the State:
+      define_key(key_name, opts)
+
+      # Accessor for new key with support for default value:
+      define_method(key_name) do
+        DoesKeyValue.log("Accessing key:#{key_name} for class:#{self.class}")
+        blob = if self.class.column_storage?
+          Hashie::Mash.new( self.send(:read_attribute, self.class.storage_column) || Hash.new )
+        elsif self.class.table_storage?
+          # TODO: Proper cache-through hash for Table-based storage
+          Hashie::Mash.new( {key_name => DoesKeyValue::Index.read_index(self, key_name)} )
+        end
+
+        value = blob.send(key_name)
+
+        return value if value
+        return key_default_value
+      end
+
+      # Manipulator for new key:
+      define_method("#{key_name}=") do |value|
+        DoesKeyValue.log("Modifying value for key:#{key_name} to value:#{value}")
+
+        if self.class.column_storage?
+          blob = Hashie::Mash.new( self.send(:read_attribute, self.class.storage_column) || Hash.new )
+          typed_value = DoesKeyValue::Util.to_type(value, key_type)
+          blob[key_name] = typed_value
+          self.send(:write_attribute, self.class.storage_column, blob.to_hash)
+
+        elsif self.class.table_storage?
+          # TODO: Proper cache-through hash for Table-based storage:
+          DoesKeyValue::Index.update_index(self, key_name, value) unless self.new_record?
+        end
+      end
+
+      # If key is indexed, add scopes, finders, and callbacks for index management:
+      if key_indexed
+
+        # With scope:
+        scope "with_#{key_name}", lambda {|value| 
+          DoesKeyValue::Index.find_objects(self, key_name, value)
+        }
+        DoesKeyValue.log("Scope with_#{key_name} added for indexed key #{key_name}")
+      
+        # Update the index after save:
+        if column_storage?
+          define_method("update_index_for_#{key_name}") do
+            DoesKeyValue::Index.update_index(self, key_name, self.send(key_name))
+          end
+          after_save "update_index_for_#{key_name}"
+        end
+
+        # Delete the index after destroy:
+        define_method("destroy_index_for_#{key_name}") do
+          DoesKeyValue::Index.delete_index(self, key_name)
+        end
+        after_destroy "destroy_index_for_#{key_name}"
+
+      end # if key_indexed
+
+
+    end
+
+
+    # Return true if this class uses column-based storage for key-value pairs:
+    def column_storage?
+      !storage_column.nil?
+    end
+
+    # Return the column used for storing key values for this class:
+    def storage_column
+      @storage_column ||= DoesKeyValue::State.instance.options_for_class(self)[:column]
+    end
+
+    # Return true if this class uses table-based storage for key-value pairs:
+    def table_storage?
+      !storage_table.nil?
+    end
+
+    # Return the table used for storing key values for this class:
+    def storage_table
+      @storage_table ||= DoesKeyValue::State.instance.options_for_class(self)[:table]
+    end
+
+    # Return a list of currently supported keys:
+    def keys
+      DoesKeyValue::State.instance.keys[self.to_s]
+    end
+
+    # Return the specific configuration for a given key:
+    def key_options(key_name)
+      DoesKeyValue::State.instance.options_for_key(self, key_name)
+    end
+
+    
+    private
+
+    # Define a new key for a class:
+    def define_key(key_name, opts={})
+      DoesKeyValue::State.instance.add_key(self, key_name, opts)
+    end
+
+  end # Accessors
+end # DoesKeyValue

data/lib/doeskeyvalue/column_storage.rb

@@ -0,0 +1,95 @@
+# AWEXOME LABS
+# DoesKeyValue
+#
+# ColumnStorage -- Support and methods for key-value pairs stored within TEXT
+#  or BLOB fields on the same table as the parent object.
+
+module DoesKeyValue
+
+  SUPPORTED_DATA_TYPES = %w(string integer decimal boolean datetime)
+
+  module ColumnStorage
+
+    # Define a supported key
+    def has_key(key_name, opts={})
+      opts = {
+        index: true,
+        type: "string",
+        default: nil
+      }.merge(opts)
+
+      key_indexed = opts[:index]
+      key_type = opts[:type].to_sym
+      key_default_value = opts[:default]
+
+      raise Exception.new("Data type not supported: #{key_type}") unless DoesKeyValue::SUPPORTED_DATA_TYPES.include?(key_type.to_s)
+
+      DoesKeyValue::State.instance.add_key(self, key_name, opts)
+      storage_column = DoesKeyValue::State.instance.options_for_class(self)[:column]
+
+      # Accessor for new key with support for default value:
+      define_method(key_name) do
+        DoesKeyValue.log("Accessing key:#{key_name} for class:#{self.class}")
+        blob = self.send(:read_attribute, storage_column) || Hash.new
+        blob = Hashie::Mash.new(blob)
+        value = blob.send(key_name)
+
+        if value
+          return value
+        elsif default_value = self.class.key_options(key_name)[:default]
+          return default_value
+        end
+      end
+
+      # Manipulator for new key:
+      define_method("#{key_name}=") do |value|
+        DoesKeyValue.log("Modifying value for key:#{key_name} to value:#{value}")
+        blob = self.send(:read_attribute, storage_column) || Hash.new
+        blob = Hashie::Mash.new(blob)
+
+        typed_value = DoesKeyValue::Util.to_type(value, key_type)
+
+        blob[key_name] = typed_value
+        self.send(:write_attribute, storage_column, blob.to_hash)
+      end
+
+      # If key is indexed, add scopes, finders, and callbacks for index management:
+      if key_indexed
+
+        # With scope:
+        scope "with_#{key_name}", lambda {|value| 
+          DoesKeyValue::Index.find_objects(self, key_name, value)
+        }
+        DoesKeyValue.log("Scope with_#{key_name} added for indexed key #{key_name}")
+      
+        # Update the index after save:
+        define_method("update_index_for_#{key_name}") do
+          DoesKeyValue::Index.update_index(self, key_name, self.send(key_name))
+        end
+        after_save "update_index_for_#{key_name}"
+
+        # Delete the index after destroy:
+        define_method("destroy_index_for_#{key_name}") do
+          DoesKeyValue::Index.delete_index(self, key_name)
+        end
+        after_destroy "destroy_index_for_#{key_name}"
+
+      end # if key_indexed
+
+
+    end
+
+
+    # Return a list of currently supported keys:
+    def keys
+      DoesKeyValue::State.instance.keys[self.to_s]
+    end
+
+    # Return the specific configuration for a given key:
+    def key_options(key_name)
+      DoesKeyValue::State.instance.options_for_key(self, key_name)
+    end
+
+
+  end # ColumnStorage
+end # DoesKeyValue

data/lib/doeskeyvalue/configuration.rb

@@ -0,0 +1,32 @@
+# AWEXOME LABS
+# DoesKeyValue : Configuration
+
+module DoesKeyValue
+
+  class Configuration
+
+    # Configurable options:
+    attr_accessor :log_level
+
+    # Declare defaults on load:
+    def initialize
+      @log_level = :silent
+    end
+
+  end # Configuration
+
+
+  # Provide an accessor to the gem configuration:
+  class << self
+    attr_accessor :configuration
+  end
+
+  # Yield the configuration to host:
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+  end
+
+  DoesKeyValue.configuration = Configuration.new
+
+end # DoesKeyValue

data/lib/doeskeyvalue/index.rb

@@ -0,0 +1,145 @@
+# AWEXOME LABS
+# DoesKeyValue
+#
+# DoesKeyValue::Index -- An AR model used for updating indexes
+
+module DoesKeyValue
+
+  class Index < ActiveRecord::Base
+
+    # The default index table (overidden individually for custom tables):
+    self.table_name = "key_value_index"
+
+    # All attributes of an index row are mass-editable:
+    attr_accessible :obj_type, :obj_id, :key_name, :key_type, 
+                    :value_string, :value_integer, :value_decimal, :value_boolean, :value_datetime
+
+
+    # Search the database for objects matching the given query for the given key:
+    def self.find_objects(klass, key_name, value)
+      object_type = klass.to_s
+      key_type = klass.key_options(key_name)[:type]
+
+      condition_set = {obj_type: object_type, key_name: key_name, key_type: key_type, "value_#{key_type}"=>value}
+      DoesKeyValue.log("Condition Set for index find: #{condition_set.inspect}")
+      table_agnostic_exec(klass) do
+        index_rows = DoesKeyValue::Index.where(condition_set)
+        object_ids = index_rows.blank? ? [] : index_rows.collect {|i| i.obj_id }
+        klass.where(:id=>object_ids)
+      end
+    end
+
+
+    # Read the appropriate index values for the given object/key combination:
+    def self.read_index(object, key_name)
+      object_type = object.class.to_s
+      object_id = object.id
+      key_type = object.class.key_options(key_name)[:type]
+
+      # Prepare the query conditions:
+      condition_set = {obj_type: object_type, obj_id: object_id, key_name: key_name}
+
+      # Access the appropriate value column of the returned index:
+      table_agnostic_exec(object.class) do 
+        DoesKeyValue::Index.where(condition_set).first().try(:send, "value_#{key_type}")
+      end
+    end
+
+
+    # Update the appropriate index with new/changed information for the given
+    # object/key/value combination:
+    def self.update_index(object, key_name, value)
+      # Log our index column values:
+      object_type = object.class.to_s
+      object_id = object.id
+      key_type = object.class.key_options(key_name)[:type]
+
+      # Prepare update conditions and manipulators:
+      update_set = {key_type: key_type}
+      condition_set = {obj_type: object_type, obj_id: object_id, key_name: key_name}
+      create_set = {obj_type: object_type, obj_id: object_id, key_name: key_name, key_type: key_type}
+
+      # Insert the new value of the correct type:
+      update_set["value_#{key_type}"] = value
+      create_set["value_#{key_type}"] = value
+
+      DoesKeyValue.log("Updating Index for class:#{object_type} key:#{key_name}:")
+      DoesKeyValue.log("update_set: #{update_set.inspect}")
+      DoesKeyValue.log("condition_set: #{condition_set.inspect}")
+      DoesKeyValue.log("create_set: #{create_set.inspect}")
+
+      # Update an index in a table-agnostic way to support table-based key-value storage in
+      # database tables other than the universal table:
+      table_agnostic_exec(object.class) do
+        updated_count = DoesKeyValue::Index.update_all( update_set, condition_set )
+        if !value.nil? && updated_count == 0
+          DoesKeyValue::Index.create( create_set )
+        end
+      end
+
+    end
+
+
+    # Delete an index record for a given object/key combination:
+    def self.delete_index(object, key_name)
+      object_type = object.class.to_s
+      object_id = object.id
+
+      deleted_count = table_agnostic_exec(object.class) do
+        DoesKeyValue::Index.delete_all(
+          obj_type: object_type, obj_id: object_id, key_name: key_name
+        )
+      end
+    end
+
+
+
+    private
+
+    # Return true only if the storage method for the given class is table:
+    def self.table_storage_for_class?(klass)
+      storage_options = DoesKeyValue::State.instance.options_for_class(klass)
+      storage_options[:table].nil? ? false : true
+    end
+
+    # Perform a block action inside of table-altered query:
+    def self.table_agnostic_exec(klass)
+      begin
+        original_table_name = DoesKeyValue::Index.table_name
+        if DoesKeyValue::Index.table_storage_for_class?(klass)
+          class_storage_options = DoesKeyValue::State.instance.options_for_class(klass)
+          if class_storage_options[:table]
+            DoesKeyValue::Index.table_name = class_storage_options[:table]
+            DoesKeyValue.log("Storage table for index changed to '#{DoesKeyValue::Index.table_name}'")
+          end
+        end
+
+        exec_result = yield
+
+        if DoesKeyValue::Index.table_storage_for_class?(klass)
+          DoesKeyValue::Index.table_name = original_table_name
+          DoesKeyValue.log("Storage table for index changed back to original '#{DoesKeyValue::Index.table_name}")
+        end
+
+        return exec_result
+
+      rescue ActiveRecord::StatementInvalid => e
+        DoesKeyValue.log("Database query statement invalid: #{e.message}")
+        if (e.message =~ /doesn't exist/)
+          DoesKeyValue.log("It appears the index table `#{DoesKeyValue::Index.table_name}` expected has not been generated.")
+          DoesKeyValue.log("To generate the necessary table run: rails generate doeskeyvalue #{DoesKeyValue::Index.table_name}")
+        end
+        raise e
+
+      ensure
+        # Ensure that the table name is always restored
+        DoesKeyValue::Index.table_name = original_table_name
+        DoesKeyValue.log("After table-agnostic execution, table name restored to '#{DoesKeyValue::Index.table_name}'")
+      end
+    end
+
+
+
+  end # Index
+
+end # DoesKeyValue