merged cont.
[opensuse:yast-rest-service.git] / webyast / vendor / plugins / static_record_cache / README.rdoc
1 = Static Record Cache
2 This plugin has two options for caching records of Static classes which change rarely or never
3 =acts_as_static_record
4 Permanently caches subclasses of ActiveRecord that contains data that changes rarely.
5
6 Includes support for:
7 * Find by Id, all, first (association lookups)
8 * Cached caluculations: <tt>Neighborhood.count</tt>s, sum, max, min
9 * Convenience lookups: <tt>Neighborhood[:seattle]</tt>
10 * Additional support for column name lookups: <tt>Neighborhood.find_by_name 'Seattle'</tt>
11
12 == Install
13
14   sudo gem install static_record_cache --source=http://gemcutter.org
15
16   script/plugin install git://github.com/blythedunham/static_record_cache.git
17
18 == Usage
19   class SomeMostlyStaticClass < ActiveRecord::Base
20     acts_as_static_record
21   end
22
23 Any finds that do not contain additional conditions, joins, and other arguments
24 become a cache call. One advantage over the query cache is that the static cache is searched
25 eliminating the need for  +ActiveRecord+ to generate SQL
26
27 When a cache key is specified with option <tt>:key</tt>, additional
28 finder methods for ids and fields such as +find_by_id+ and +find_by_name_and_mother+
29 are overwritten to search the cache when no arguments (conditions) are specified.
30 If the cache key is not a column, then a finder method will be defined.
31   acts_as_static_record :key => :some_instance_method
32 Will define <tt>find_by_some_instance_method(value)</tt>
33
34 === Options
35 * <tt>:key</tt> - a method or column of the instance used to specify a cache key. This should be unique.
36 * <tt>:find</tt> an additional find scope to specify <tt>:conditions</tt>,<tt>:joins</tt>, <tt>:select</tt>, <tt>:joins</ff> etc
37 * <tt>:find_by_attribute_support</tt> - set to true to add additional functionality for finders such as +find_by_id_and_name+ to use a cache search. This option is probably best for Rails 2.3
38 * <tt>:lookup_key</tt> - access the record from the class by a key name like <tt>User[:snowgiraffe]</tt>. <tt>:lookup_key</tt> is the column on which do do the lookup.
39
40 === Examples
41 Caches on Id and telephone carrier name
42  class TelephoneCarrier < ActiveRecord::Base
43    acts_as_static_method :key => :name
44  end
45
46 Caches the WhiteList on phone_number_digits (in addition to ID)
47  create_table :sms_white_list, :force => true do |t|
48    t.column :phone_number_id, :integer, :null => false
49    t.column :notes, :string, :length => 100, :default => nil
50  end
51
52  class SmsWhiteList < ActiveRecord::Base
53    belongs_to :phone_number
54
55    acts_as_static_record :key => :phone_number_digits,
56               :find => :select => 'carriers.*, phone_number.number as phone_number_digits'
57                        :joins => 'inner join phone_numbers on phone_numbers.carrier_id = carriers.id'
58
59    def phone_number_digits
60      self['phone_number_digits']||self.phone_number.number
61    end
62  end
63
64 Direct cache hits
65  SmsWhiteList.find_by_phone_number_digits('12065551234')
66  SmsWhiteList.find_by_id(5)
67  SmsWhiteList.find :all
68
69 Searched cache hits
70  SmsWhiteList.find_by_notes('Some note')
71
72 ==Calculation Support
73 Now with +calculate+ support for +sum+, +min+, and +max+ for integer columns and +count+ for all columns
74 Cache hits do not occur if options other than +distinct+ are used.
75
76 Cache hits:
77  Neighborhood.count
78  Neighborhood.count :name, :distinct => true
79  Neighborhood.sum :id
80  Neighborhood.max :id
81 Not cache hits:
82  Neighborhood.max :name
83  Neighborhood.count :zip_code, :conditions => ['name = ?', 'Seattle']
84
85 ==Convenience lookup
86 Similar to acts_as_enumeration model returns the record where the
87 <tt>acts_as_static_record :key</tt> option matches +lookup+
88 If no key is specified, the primary_id column is used
89
90   class User < ActiveRecord::Base
91     acts_as_static_record :key => :user_name
92   end
93
94 Then later we can reference the objects by the user_name
95   User[:blythe]
96   User['snowgiraffe']
97
98 The key used will be the underscore version of the name. Punctuation marks
99 are removed. The following are equivalent:
100  User[:blythe_snowgiraffeawesome]
101  User['blythe-SNOWGIRaffe   AWESome']
102
103  user = User.first
104  User[user.user_name] == user
105
106
107
108 = StaticActiveRecordContext
109
110 Extends the active_record_context plugin,
111 http://svn.techno-weenie.net/projects/plugins/active_record_context/
112 to permanently cache records for an ActiveRecord subclass
113
114 Finds on records IDS (as used by associations)  will be cached for the life of the class.
115 This works both in and outside a  with_context block.
116
117 == Example
118
119   class TelephoneCarriers < ActiveRecord::Base
120     extend StaticActiveRecordContext
121   end
122
123   phone_number.carrier
124
125 === Developers
126 * Blythe Dunham http://snowgiraffe.com
127
128 === Docs
129 * Rdoc:           http://snowgiraffe.com/rdocs/static_record_cache/
130 === Homepage
131 * Github Project: http://github.com/blythedunham/static_record_cache/tree/master
132 * Install:  <tt>script/plugin install git://github.com/blythedunham/static_record_cache.git</tt>
133
134
135
136
137
138