Module: Merb::Cache::Controller::ClassMethods

Included in:
Merb::Controller
Defined in:
lib/merb-cache/merb_ext/controller/class_methods.rb

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.extended(base) ⇒ Object 



3
4
5
6
 
# File 'lib/merb-cache/merb_ext/controller/class_methods.rb', line 3

def self.extended(base)
  base.send :class_inheritable_accessor, :_cache
  base._cache = {}
end

Instance Method Details

#_controller_and_conditions(action, request_hash) ⇒ Array[Controller, Hash]

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Note:

in the request hash, :params, :uri and :method are supported. Additionally :store and :stores specify which store to use.

Used by cache?, cached?, cache_for and delete_cache_for to generate the controller from the given parameters.

Parameters:

  • action (String) —

    the cached action

  • request_hash (Hash) —

    params from the request.

Returns:

  • (Array[Controller, Hash]) —

    the controller built using the request corresponding to params the conditions for the cached action



234
235
236
237
238
239
240
241
242
 
# File 'lib/merb-cache/merb_ext/controller/class_methods.rb', line 234

def _controller_and_conditions(action, request_hash)
  conditions = self._cache[action]
  conditions.merge!(request_hash.only(:store, :stores))
  request_hash.extract!(:store, :stores)
  controller = new(build_request(request_hash))
  controller.action_name = action

  [controller, conditions]
end

#build_request(request_hash = {}) ⇒ Request

Note:

Acceptable options for the request hash

  • :uri The uri of the request

  • :method The http method (defaults to :get)

  • :params The params

  • any env variable you may need

Builds a request that will be sent to the merb worker process to be cached without holding some poor user up generating the cache (through run_later)

Examples:

build_request(:params => => @article.id, :method => :put, :uri => build_url(:article, @article)}) # a request corresponding to the update action of a resourceful controller

Parameters:

  • request_hash (Hash) (defaults to: {}) —

    hash used to describe the request

Returns:

  • (Request) —

    A request for the given arguments



212
213
214
 
# File 'lib/merb-cache/merb_ext/controller/class_methods.rb', line 212

def build_request(request_hash = {})
  Merb::Cache::CacheRequest.new(request_hash.delete(:uri), request_hash.delete(:params), request_hash)
end

#build_url(*args) ⇒ Object

See Also:

  • Router.url


217
218
219
 
# File 'lib/merb-cache/merb_ext/controller/class_methods.rb', line 217

def build_url(*args)
  Merb::Router.url(*args)
end

#cache(*actions) ⇒ Object

Note:

Specific options for cache:

- :store (or :stores) use the specified store
- :params list of params to pass to the store (see _parameters_and_conditions)

cache is an alias to cache_action, it will take multiple :actions and pass the conditions hash for each action

Examples:

cache :index, :show, :expire_in => 30 # caches the index and show action for 30 seconds

cache :index, :store => :page_store # caches the index action using the page store

cache :index, :params => [:page, :q], :store => :action_store # caches the index action using the action store and passing the :page and :q params to the action store (NB. :params => <Array> has no effect on the page store)

Parameters:

  • *actions (Array[Symbol]) —

    actions to cache

  • options (Hash) —

    Conditions passed to the store and two options specific to cache



30
31
32
33
 
# File 'lib/merb-cache/merb_ext/controller/class_methods.rb', line 30

def cache(*actions)
  options = extract_options_from_args!(actions) || {}
  actions.each {|a| cache_action(a, options)}
end

#cache!(conditions = {}) ⇒ Object 



9
10
11
12
 
# File 'lib/merb-cache/merb_ext/controller/class_methods.rb', line 9

def cache!(conditions = {})
  before(:_cache_before, conditions.only(:if, :unless).merge(:with => conditions))
  after(:_cache_after, conditions.only(:if, :unless).merge(:with => conditions))
end

#cache_action(action, conditions = {}) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

cache action will cache the action Parameters are the same as cache but only one action is allowed



39
40
41
42
43
44
45
 
# File 'lib/merb-cache/merb_ext/controller/class_methods.rb', line 39

def cache_action(action, conditions = {})
  self._cache[action] = conditions
  before("_cache_#{action}_before", conditions.only(:if, :unless).merge(:with => [conditions], :only => action))
  after("_cache_#{action}_after", conditions.only(:if, :unless).merge(:with => [conditions], :only => action))
  alias_method "_cache_#{action}_before", :_cache_before
  alias_method "_cache_#{action}_after",  :_cache_after
end

#cache_for(action, params = {}) ⇒ Object

Note:

if not specified, the default http method is :get and the default uri is ‘/’

Returns the cache for the action with the given request

Examples:

Project.cache_for :index, :uri => ‘/projects’, :params => => ‘test’, :method => :get

Parameters:

  • action (String) —

    action to check

  • request_hash (Hash) —

    The params that the request would have. :uri and :method are also supported to indicate the :uri and :method of the request. :store and :stores indicate the cache store to use.

Returns:

  • (Object) —

    The content of the cache if available, else nil



103
104
105
106
 
# File 'lib/merb-cache/merb_ext/controller/class_methods.rb', line 103

def cache_for(action, params = {})
  controller, conditions = _controller_and_conditions(action, params)
  Merb::Cache[controller._lookup_store(conditions)].read(controller, *controller._parameters_and_conditions(conditions).first)      
end

#cached?(action, params = {}) ⇒ TrueClass, FalseClass

Note:

if not specified, the default http method is :get and the default uri is ‘/’

Checks if the action called with a certain request has been cached or not.

Examples:

Project.caches? :index, :uri => ‘/projects’, :params => => ‘test’, :method => :get

Parameters:

  • action (String) —

    action to check

  • request_hash (Hash) —

    The params that the request would have. :uri and :method are also supported to indicate the :uri and :method of the request. :store and :stores indicate the cache store to use.

Returns:

  • (TrueClass, FalseClass) —

    True if such a request has been cached



83
84
85
86
 
# File 'lib/merb-cache/merb_ext/controller/class_methods.rb', line 83

def cached?(action, params = {})
  controller, conditions = _controller_and_conditions(action, params)
  Merb::Cache[controller._lookup_store(conditions)].exists?(controller, *controller._parameters_and_conditions(conditions))
end

#caches?(action, params = {}) ⇒ TrueClass, FalseClass

Note:

if not specified, the default http method is :get and the default uri is ‘/’

Checks if the action called with a certain request would be cached or not. Usefull for troubleshooting problems

Examples:

Project.caches? :index, :uri => ‘/projects’, :params => => ‘test’, :method => :get

Project.caches? :show, :uri => url(:project, @project), :params => => @project.id

Parameters:

  • action (String) —

    action to check

  • request_hash (Hash) —

    The params that the request would have. :uri and :method are also supported to indicate the :uri and :method of the request. :store and :stores indicate the cache store to use.

Returns:

  • (TrueClass, FalseClass) —

    True if such a request would be cached



63
64
65
66
 
# File 'lib/merb-cache/merb_ext/controller/class_methods.rb', line 63

def caches?(action, params = {})
  controller, conditions = _controller_and_conditions(action, params)
  Merb::Cache[controller._lookup_store(conditions)].writable?(controller, *controller._parameters_and_conditions(conditions))
end

#delete_cache_for(action, params = {}) ⇒ Object

Note:

if not specified, the default http method is :get and the default uri is ‘/’

Deletes the cache for the action with the given request

Examples:

Project.delete_cache_for :index, :uri => ‘/projects’, :params => => ‘test’, :method => :get

Parameters:

  • action (String) —

    action

  • request_hash (Hash) —

    The params that the request would have. :uri and :method are also supported to indicate the :uri and :method of the request. :store and :stores indicate the cache store to use.



121
122
123
124
 
# File 'lib/merb-cache/merb_ext/controller/class_methods.rb', line 121

def delete_cache_for(action, params = {})
  controller, conditions = _controller_and_conditions(action, params)
  Merb::Cache[controller._lookup_store(conditions)].delete(controller, *controller._parameters_and_conditions(conditions).first)      
end

#eager_cache(trigger_actions, target = nil, opts = {}, &blk) ⇒ Object

Note:

Valid request options are:

- :uri the uri of the resource you want to eager cache (needed by the page store but can be provided instead by a block)
- :method http method used (defaults to :get)

Caches specified with eager_cache will be run after #trigger_action has been run without holding some poor user up generating the cache (through run_later)

Examples:

eager_cache :update, :index, :uri => ‘/articles’ # When the update action is completed, a get request to :index with ‘/articles’ uri will be cached (if you use the page store, this will be stored in ‘/articles.html’)

eager_cache :create, :index # Same after the create action but since no uri is given, the current uri is used with the default http method (:get). Useful default for resource controllers

eager_cache(:create, [Timeline, :index]) :uri => build_url(:timelines)}

Parameters:

  • trigger_action (Symbol, Array[*Symbol]) —

    The actions that will trigger the eager caching

  • target (Array[Controller,Symbol], Symbol) (defaults to: nil) —

    the target option to cache (if no controller is given, the current controller is used)

  • opts (Hash) (defaults to: {}) —

    Request options. See note for details.

  • blk (Block) —

    Block run to generate the request or controller used for eager caching after trigger_action has run



144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/merb-cache/merb_ext/controller/class_methods.rb', line 144

def eager_cache(trigger_actions, target = nil, opts = {}, &blk)
  trigger_actions = [*trigger_actions]
  target, conditions = nil, target if target.is_a? Hash
  
  trigger_actions.each do |trigger_action|

    if target.is_a? Array
      target_controller, target_action = *target
    else
      target_controller, target_action = self, (target || trigger_action)
    end

    after("_eager_cache_#{trigger_action}_to_#{target_controller.name.snake_case}__#{target_action}_after", opts.only(:if, :unless).merge(:with => [target_controller, target_action, opts, blk], :only => trigger_action))
    alias_method "_eager_cache_#{trigger_action}_to_#{target_controller.name.snake_case}__#{target_action}_after", :_eager_cache_after
  end
end

#eager_dispatch(action, params = {}, env = {}, blk = nil) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Dispatches eager caches to a worker process

Parameters:

  • action (String) —

    The actiont to dispatch

  • params (Hash) (defaults to: {}) —

    params of the request (passed to the block)

  • env (Hash) (defaults to: {}) —

    environment variables of the request (passed to the block)

  • blk (Block) (defaults to: nil) —

    block used to build the request (should return a hash, request or a controller)



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
 
# File 'lib/merb-cache/merb_ext/controller/class_methods.rb', line 169

def eager_dispatch(action, params = {}, env = {}, blk = nil)
  kontroller = if blk.nil?
    new(build_request(env))
  else
    result = case blk.arity
      when 0  then  blk[]
      when 1  then  blk[params]
      else          blk[*[params, env]]
    end

    case result
    when NilClass         then new(build_request(env))
    when Hash, Mash       then new(build_request(result))
    when Merb::Request    then new(result)
    when Merb::Controller then result
    else raise ArgumentError, "Block to eager_cache must return nil, the env Hash, a Request object, or a Controller object"
    end
  end

  kontroller.force_cache!

  kontroller._dispatch(action)

  kontroller
end