-
Notifications
You must be signed in to change notification settings - Fork 9
/
enumerate_by.rb
391 lines (357 loc) · 14.3 KB
/
enumerate_by.rb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
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 => 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} #{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 => 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)
records = find_all_by_enumerator(enumerators)
missing = [enumerators].flatten - 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 }
else
super
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
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!
delete_all(['id NOT IN (?)', records.map {|record| record[:id]}])
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!
delete_all(['id NOT IN (?)', records.map {|record| record[:id]}])
# 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.is_a?(String) ? self == self.class.find_by_enumerator!(arg) : super
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