require 'enumerate_by/extensions/associations'
require 'enumerate_by/extensions/base_conditions'
require 'enumerate_by/extensions/serializer'
require 'enumerate_by/extensions/xml_serializer'
# An enumeration defines a finite set of enumerators which (often) have no
# numerical order. This extension provides a general technique for using
# ActiveRecord classes to define enumerations.
module EnumerateBy
# Whether to enable enumeration caching (default is true)
mattr_accessor :perform_caching
self.perform_caching = true
module MacroMethods
def self.extended(base) #:nodoc:
base.class_eval do
# Tracks which associations are backed by an enumeration
# {"foreign key" => "association name"}
class_inheritable_accessor :enumeration_associations
self.enumeration_associations = {}
end
end
# Indicates that this class is an enumeration.
#
# The default attribute used to enumerate the class is +name+. You can
# override this by specifying a custom attribute that will be used to
# *uniquely* reference a record.
#
# *Note* that a presence and uniqueness validation is automatically
# defined for the given attribute since all records must have this value
# in order to be properly enumerated.
#
# Configuration options:
# * <tt>:cache</tt> - Whether to cache all finder queries for this
# enumeration. Default is true.
#
# == Defining enumerators
#
# The enumerators of the class uniquely identify each record in the
# table. The enumerator value is based on the attribute described above.
# In scenarios where the records are managed in code (like colors,
# countries, states, etc.), records can be automatically synchronized
# via #bootstrap.
#
# == Accessing records
#
# The actual records for an enumeration can be accessed via shortcut
# helpers like so:
#
# Color['red'] # => #<Color id: 1, name: "red">
# Color['green'] # => #<Color id: 2, name: "green">
#
# When caching is enabled, these lookup queries are cached so that there
# is no performance hit.
#
# == Associations
#
# When using enumerations together with +belongs_to+ associations, the
# enumerator value can be used as a shortcut for assigning the association.
#
# In addition, the enumerator value is automatically used during
# serialization (xml and json) of the associated record instead of the
# foreign key for the association.
#
# For more information about how to use enumerations with associations,
# see EnumerateBy::Extensions::Associations and EnumerateBy::Extensions::Serializer.
#
# === Finders
#
# In order to be consistent by always using enumerators to reference
# records, a set of finder extensions are added to allow searching
# for records like so:
#
# class Car < ActiveRecord::Base
# belongs_to :color
# end
#
# Car.find_by_color('red')
# Car.all(:conditions => {:color => 'red'})
#
# For more information about finders, see EnumerateBy::Extensions::BaseConditions.
def enumerate_by(attribute = :name, options = {})
options.reverse_merge!(:cache => true)
options.assert_valid_keys(:cache)
extend EnumerateBy::ClassMethods
extend EnumerateBy::Bootstrapped
include EnumerateBy::InstanceMethods
# The attribute representing a record's enumerator
cattr_accessor :enumerator_attribute
self.enumerator_attribute = attribute
# Whether to perform caching of enumerators within finder queries
cattr_accessor :perform_enumerator_caching
self.perform_enumerator_caching = options[:cache]
# The cache store to use for queries (default is a memory store)
cattr_accessor :enumerator_cache_store
self.enumerator_cache_store = ActiveSupport::Cache::MemoryStore.new
validates_presence_of attribute
validates_uniqueness_of attribute
end
# Does this class define an enumeration? Always false.
def enumeration?
false
end
end
module ClassMethods
# Does this class define an enumeration? Always true.
def enumeration?
true
end
# Finds the record that is associated with the given enumerator. The
# attribute that defines the enumerator is based on what was specified
# when calling +enumerate_by+.
#
# For example,
#
# Color.find_by_enumerator('red') # => #<Color id: 1, name: "red">
# Color.find_by_enumerator('invalid') # => nil
def find_by_enumerator(enumerator)
first(:conditions => {enumerator_attribute => typecast_enumerator(enumerator)})
end
# Finds the record that is associated with the given enumerator. If no
# record is found, then an ActiveRecord::RecordNotFound exception is
# raised.
#
# For example,
#
# Color['red'] # => #<Color id: 1, name: "red">
# Color['invalid'] # => ActiveRecord::RecordNotFound: Couldn't find Color with name "red"
#
# To avoid raising an exception on invalid enumerators, use +find_by_enumerator+.
def find_by_enumerator!(enumerator)
find_by_enumerator(enumerator) || raise(ActiveRecord::RecordNotFound, "Couldn't find #{name} with #{enumerator_attribute} #{typecast_enumerator(enumerator).inspect}")
end
alias_method :[], :find_by_enumerator!
# Finds records with the given enumerators.
#
# For example,
#
# Color.find_all_by_enumerator(['red', 'green']) # => [#<Color id: 1, name: "red">, #<Color id: 1, name: "green">]
# Color.find_all_by_enumerator('invalid') # => []
def find_all_by_enumerator(enumerators)
all(:conditions => {enumerator_attribute => typecast_enumerator(enumerators)})
end
# Finds records with the given enumerators. If no record is found for a
# particular enumerator, then an ActiveRecord::RecordNotFound exception
# is raised.
#
# For Example,
#
# Color.find_all_by_enumerator!(['red', 'green']) # => [#<Color id: 1, name: "red">, #<Color id: 1, name: "green">]
# Color.find_all_by_enumerator!('invalid') # => ActiveRecord::RecordNotFound: Couldn't find Color with name(s) "invalid"
#
# To avoid raising an exception on invalid enumerators, use +find_all_by_enumerator+.
def find_all_by_enumerator!(enumerators)
enumerators = [enumerators].flatten
records = find_all_by_enumerator(enumerators)
missing = enumerators - records.map(&:enumerator)
missing.empty? ? records : raise(ActiveRecord::RecordNotFound, "Couldn't find #{name} with #{enumerator_attribute}(s) #{missing.map(&:inspect).to_sentence}")
end
# Adds support for looking up results from the enumeration cache for
# before querying the database.
#
# This allows for enumerations to permanently cache find queries, avoiding
# unnecessary lookups in the database.
[:find_by_sql, :exists?, :calculate].each do |method|
define_method(method) do |*args|
if EnumerateBy.perform_caching && perform_enumerator_caching
enumerator_cache_store.fetch([method] + args) { super(*args) }
else
super(*args)
end
end
end
# Temporarily disables the enumeration cache (as well as the query cache)
# within the context of the given block if the enumeration is configured
# to allow caching.
def uncached
old = perform_enumerator_caching
self.perform_enumerator_caching = false
super
ensure
self.perform_enumerator_caching = old
end
private
# Typecasts the given enumerator to its actual value stored in the
# database. This will only convert symbols to strings. All other values
# will remain in the same type.
def typecast_enumerator(enumerator)
if enumerator.is_a?(Array)
enumerator.flatten!
enumerator.map! {|value| typecast_enumerator(value)}
enumerator
else
enumerator.is_a?(Symbol) ? enumerator.to_s : enumerator
end
end
end
module Bootstrapped
# Synchronizes the given records with existing ones. This ensures that
# only the correct and most up-to-date records exist in the database.
# The sync process is as follows:
# * Any existing record that doesn't match is deleted
# * Existing records with matches are updated based on the given attributes for that record
# * Records that don't exist are created
#
# To create records that can be referenced elsewhere in the database, an
# id should always be specified. Otherwise, records may change id each
# time they are bootstrapped.
#
# == Examples
#
# class Color < ActiveRecord::Base
# enumerate_by :name
#
# bootstrap(
# {:id => 1, :name => 'red'},
# {:id => 2, :name => 'blue'},
# {:id => 3, :name => 'green'}
# )
# end
#
# In the above model, the +colors+ table will be synchronized with the 3
# records passed into the +bootstrap+ helper. Any existing records that
# do not match those 3 are deleted. Otherwise, they are either created or
# updated with the attributes specified.
#
# == Defaults
#
# In addition to *always* synchronizing certain attributes, an additional
# +defaults+ option can be given to indicate that certain attributes
# should only be synchronized if they haven't been modified in the
# database.
#
# For example,
#
# class Color < ActiveRecord::Base
# enumerate_by :name
#
# bootstrap(
# {:id => 1, :name => 'red', :defaults => {:html => '#f00'}},
# {:id => 2, :name => 'blue', :defaults => {:html => '#0f0'}},
# {:id => 3, :name => 'green', :defaults => {:html => '#00f'}}
# )
# end
#
# In the above model, the +name+ attribute will always be updated on
# existing records in the database. However, the +html+ attribute will
# only be synchronized if the attribute is nil in the database.
# Otherwise, any changes to that column remain there.
def bootstrap(*records)
uncached do
# Remove records that are no longer being used
records.flatten!
ids = records.map {|record| record[:id]}.compact
delete_all(ids.any? ? ['id NOT IN (?)', ids] : nil)
# Find remaining existing records (to be updated)
existing = all.inject({}) {|existing, record| existing[record.id] = record; existing}
records.map! do |attributes|
attributes.symbolize_keys!
defaults = attributes.delete(:defaults)
# Update with new attributes
record =
if record = existing[attributes[:id]]
attributes.merge!(defaults.delete_if {|attribute, value| record.send("#{attribute}?")}) if defaults
record.attributes = attributes
record
else
attributes.merge!(defaults) if defaults
new(attributes)
end
record.id = attributes[:id]
# Force failed saves to stop execution
record.save!
record
end
records
end
end
# Quickly synchronizes the given records with the existing ones. This
# skips ActiveRecord altogether, interacting directly with the connection
# instead. As a result, certain features are not available when being
# bootstrapped, including:
# * Callbacks
# * Validations
# * Transactions
# * Timestamps
# * Dirty attributes
#
# Also note that records are created directly without creating instances
# of the model. As a result, all of the attributes for the record must be
# specified.
#
# This produces a significant performance increase when bootstrapping more
# than several hundred records.
#
# See EnumerateBy::Bootstrapped#bootstrap for information about usage.
def fast_bootstrap(*records)
# Remove records that are no longer being used
records.flatten!
ids = records.map {|record| record[:id]}.compact
delete_all(ids.any? ? ['id NOT IN (?)', ids] : nil)
# Find remaining existing records (to be updated)
quoted_table_name = self.quoted_table_name
existing = connection.select_all("SELECT * FROM #{quoted_table_name}").inject({}) {|existing, record| existing[record['id'].to_i] = record; existing}
records.each do |attributes|
attributes.stringify_keys!
if defaults = attributes.delete('defaults')
defaults.stringify_keys!
end
id = attributes['id']
if existing_attributes = existing[id]
# Record exists: Update attributes
attributes.delete('id')
attributes.merge!(defaults.delete_if {|attribute, value| !existing_attributes[attribute].nil?}) if defaults
update_all(attributes, :id => id)
else
# Record doesn't exist: create new one
attributes.merge!(defaults) if defaults
column_names = []
values = []
attributes.each do |column_name, value|
column_names << connection.quote_column_name(column_name)
values << connection.quote(value, columns_hash[column_name])
end
connection.insert(
"INSERT INTO #{quoted_table_name} (#{column_names * ', '}) VALUES(#{values * ', '})",
"#{name} Create", primary_key, id, sequence_name
)
end
end
true
end
end
module InstanceMethods
# Whether or not this record is equal to the given value. If the value is
# a String, then it is compared against the enumerator. Otherwise,
# ActiveRecord's default equality comparator is used.
def ==(arg)
arg.nil? || arg.is_a?(self.class) ? super : self == self.class.find_by_enumerator!(arg)
end
# Determines whether this enumeration is in the given list.
#
# For example,
#
# color = Color.find_by_name('red') # => #<Color id: 1, name: "red">
# color.in?('green') # => false
# color.in?('red', 'green') # => true
def in?(*list)
list.any? {|item| self === item}
end
# A helper method for getting the current value of the enumerator
# attribute for this record. For example, if this record's model is
# enumerated by the attribute +name+, then this will return the current
# value for +name+.
def enumerator
send(enumerator_attribute)
end
# Stringifies the record typecasted to the enumerator value.
#
# For example,
#
# color = Color.find_by_name('red') # => #<Color id: 1, name: "red">
# color.to_s # => "red"
def to_s
to_str
end
# Add support for equality comparison with strings
def to_str
enumerator.to_s
end
end
end
ActiveRecord::Base.class_eval do
extend EnumerateBy::MacroMethods
end
