diff --git a/actionpack/lib/action_controller/caching.rb b/actionpack/lib/action_controller/caching.rb index be29099fbe..fc27a0774b 100644 --- a/actionpack/lib/action_controller/caching.rb +++ b/actionpack/lib/action_controller/caching.rb @@ -23,10 +23,10 @@ module ActionController #:nodoc: # Configuration examples (MemoryStore is the default): # # config.action_controller.cache_store = :memory_store - # config.action_controller.cache_store = :file_store, "/path/to/cache/directory" - # config.action_controller.cache_store = :mem_cache_store, "localhost" - # config.action_controller.cache_store = :mem_cache_store, Memcached::Rails.new("localhost:11211") - # config.action_controller.cache_store = MyOwnStore.new("parameter") + # config.action_controller.cache_store = :file_store, '/path/to/cache/directory' + # config.action_controller.cache_store = :mem_cache_store, 'localhost' + # config.action_controller.cache_store = :mem_cache_store, Memcached::Rails.new('localhost:11211') + # config.action_controller.cache_store = MyOwnStore.new('parameter') module Caching extend ActiveSupport::Concern extend ActiveSupport::Autoload @@ -73,7 +73,7 @@ module ActionController #:nodoc: end protected - # Convenience accessor + # Convenience accessor. def cache(key, options = {}, &block) if cache_configured? cache_store.fetch(ActiveSupport::Cache.expand_cache_key(key, :controller), options, &block) diff --git a/actionpack/lib/action_controller/caching/actions.rb b/actionpack/lib/action_controller/caching/actions.rb index eb3aa05a25..bf16fe267c 100644 --- a/actionpack/lib/action_controller/caching/actions.rb +++ b/actionpack/lib/action_controller/caching/actions.rb @@ -1,16 +1,16 @@ require 'set' -module ActionController #:nodoc: +module ActionController module Caching # Action caching is similar to page caching by the fact that the entire # output of the response is cached, but unlike page caching, every # request still goes through Action Pack. The key benefit of this is # that filters run before the cache is served, which allows for # authentication and other restrictions on whether someone is allowed - # to execute such action. Example: + # to execute such action. # # class ListsController < ApplicationController - # before_filter :authenticate, :except => :public + # before_filter :authenticate, except: :public # # caches_page :public # caches_action :index, :show @@ -35,8 +35,8 @@ module ActionController #:nodoc: # http://david.example.com/lists.xml # are treated like separate requests and so are cached separately. # Keep in mind when expiring an action cache that - # :action => 'lists' is not the same as - # :action => 'list', :format => :xml. + # action: 'lists' is not the same as + # action: 'list', format: :xml. # # You can modify the default action cache path by passing a # :cache_path option. This will be passed directly to @@ -53,18 +53,18 @@ module ActionController #:nodoc: # The following example depicts some of the points made above: # # class ListsController < ApplicationController - # before_filter :authenticate, :except => :public + # before_filter :authenticate, except: :public # # caches_page :public # - # caches_action :index, :if => Proc.new do + # caches_action :index, if: Proc.new do # !request.format.json? # cache if is not a JSON request # end # - # caches_action :show, :cache_path => { :project => 1 }, - # :expires_in => 1.hour + # caches_action :show, cache_path: { project: 1 }, + # expires_in: 1.hour # - # caches_action :feed, :cache_path => Proc.new do + # caches_action :feed, cache_path: Proc.new do # if params[:user_id] # user_list_url(params[:user_id, params[:id]) # else @@ -73,7 +73,7 @@ module ActionController #:nodoc: # end # end # - # If you pass :layout => false, it will only cache your action + # If you pass layout: false, it will only cache your action # content. That's useful when your layout has dynamic information. # # Warning: If the format of the request is determined by the Accept HTTP @@ -162,9 +162,9 @@ module ActionController #:nodoc: class ActionCachePath attr_reader :path, :extension - # If +infer_extension+ is true, the cache path extension is looked up from the request's + # If +infer_extension+ is +true+, the cache path extension is looked up from the request's # path and format. This is desirable when reading and writing the cache, but not when - # expiring the cache - expire_action should expire the same files regardless of the + # expiring the cache - +expire_action+ should expire the same files regardless of the # request format. def initialize(controller, options = {}, infer_extension = true) if infer_extension diff --git a/actionpack/lib/action_controller/caching/fragments.rb b/actionpack/lib/action_controller/caching/fragments.rb index 9c77b0ccf4..879d5fdd94 100644 --- a/actionpack/lib/action_controller/caching/fragments.rb +++ b/actionpack/lib/action_controller/caching/fragments.rb @@ -1,29 +1,29 @@ -module ActionController #:nodoc: +module ActionController module Caching - # Fragment caching is used for caching various blocks within + # Fragment caching is used for caching various blocks within # views without caching the entire action as a whole. This is - # useful when certain elements of an action change frequently or - # depend on complicated state while other parts rarely change or + # useful when certain elements of an action change frequently or + # depend on complicated state while other parts rarely change or # can be shared amongst multiple parties. The caching is done using - # the cache helper available in the Action View. See + # the +cache+ helper available in the Action View. See # ActionView::Helpers::CacheHelper for more information. # # While it's strongly recommended that you use key-based cache # expiration (see links in CacheHelper for more information), # it is also possible to manually expire caches. For example: # - # expire_fragment("name_of_cache") + # expire_fragment('name_of_cache') module Fragments - # Given a key (as described in expire_fragment), returns - # a key suitable for use in reading, writing, or expiring a + # Given a key (as described in +expire_fragment+), returns + # a key suitable for use in reading, writing, or expiring a # cached fragment. All keys are prefixed with views/ and uses # ActiveSupport::Cache.expand_cache_key for the expansion. def fragment_cache_key(key) ActiveSupport::Cache.expand_cache_key(key.is_a?(Hash) ? url_for(key).split("://").last : key, :views) end - # Writes content to the location signified by - # key (see expire_fragment for acceptable formats). + # Writes +content+ to the location signified by + # +key+ (see +expire_fragment+ for acceptable formats). def write_fragment(key, content, options = nil) return content unless cache_configured? @@ -35,8 +35,8 @@ module ActionController #:nodoc: content end - # Reads a cached fragment from the location signified by key - # (see expire_fragment for acceptable formats). + # Reads a cached fragment from the location signified by +key+ + # (see +expire_fragment+ for acceptable formats). def read_fragment(key, options = nil) return unless cache_configured? @@ -47,8 +47,8 @@ module ActionController #:nodoc: end end - # Check if a cached fragment from the location signified by - # key exists (see expire_fragment for acceptable formats) + # Check if a cached fragment from the location signified by + # +key+ exists (see +expire_fragment+ for acceptable formats). def fragment_exist?(key, options = nil) return unless cache_configured? key = fragment_cache_key(key) @@ -65,7 +65,7 @@ module ActionController #:nodoc: # * String - This would normally take the form of a path, like # pages/45/notes. # * Hash - Treated as an implicit call to +url_for+, like - # {:controller => "pages", :action => "notes", :id => 45} + # { controller: 'pages', action: 'notes', id: 45} # * Regexp - Will remove any fragment that matches, so # %r{pages/\d*/notes} might remove all notes. Make sure you # don't use anchors in the regex (^ or $) because @@ -74,8 +74,8 @@ module ActionController #:nodoc: # only supported on caches that can iterate over all keys (unlike # memcached). # - # +options+ is passed through to the cache store's delete - # method (or delete_matched, for Regexp keys.) + # +options+ is passed through to the cache store's +delete+ + # method (or delete_matched, for Regexp keys). def expire_fragment(key, options = nil) return unless cache_configured? key = fragment_cache_key(key) unless key.is_a?(Regexp) @@ -89,7 +89,7 @@ module ActionController #:nodoc: end end - def instrument_fragment_cache(name, key) + def instrument_fragment_cache(name, key) # :nodoc: ActiveSupport::Notifications.instrument("#{name}.action_controller", :key => key){ yield } end end diff --git a/actionpack/lib/action_controller/caching/pages.rb b/actionpack/lib/action_controller/caching/pages.rb index 73b8cd383c..3cf8d965ff 100644 --- a/actionpack/lib/action_controller/caching/pages.rb +++ b/actionpack/lib/action_controller/caching/pages.rb @@ -1,60 +1,72 @@ require 'fileutils' require 'active_support/core_ext/class/attribute_accessors' -module ActionController #:nodoc: +module ActionController module Caching - # Page caching is an approach to caching where the entire action output of is stored as a HTML file that the web server - # can serve without going through Action Pack. This is the fastest way to cache your content as opposed to going dynamically - # through the process of generating the content. Unfortunately, this incredible speed-up is only available to stateless pages - # where all visitors are treated the same. Content management systems -- including weblogs and wikis -- have many pages that are - # a great fit for this approach, but account-based systems where people log in and manipulate their own data are often less - # likely candidates. + # Page caching is an approach to caching where the entire action output of is + # stored as a HTML file that the web server can serve without going through + # Action Pack. This is the fastest way to cache your content as opposed to going + # dynamically through the process of generating the content. Unfortunately, this + # incredible speed-up is only available to stateless pages where all visitors are + # treated the same. Content management systems -- including weblogs and wikis -- + # have many pages that are a great fit for this approach, but account-based systems + # where people log in and manipulate their own data are often less likely candidates. # - # Specifying which actions to cache is done through the caches_page class method: + # Specifying which actions to cache is done through the +caches_page+ class method: # # class WeblogController < ActionController::Base # caches_page :show, :new # end # - # This will generate cache files such as weblog/show/5.html and weblog/new.html, which match the URLs used - # that would normally trigger dynamic page generation. Page caching works by configuring a web server to first check for the - # existence of files on disk, and to serve them directly when found, without passing the request through to Action Pack. - # This is much faster than handling the full dynamic request in the usual way. + # This will generate cache files such as weblog/show/5.html and + # weblog/new.html, which match the URLs used that would normally trigger + # dynamic page generation. Page caching works by configuring a web server to first + # check for the existence of files on disk, and to serve them directly when found, + # without passing the request through to Action Pack. This is much faster than + # handling the full dynamic request in the usual way. # - # Expiration of the cache is handled by deleting the cached file, which results in a lazy regeneration approach where the cache - # is not restored before another hit is made against it. The API for doing so mimics the options from +url_for+ and friends: + # Expiration of the cache is handled by deleting the cached file, which results + # in a lazy regeneration approach where the cache is not restored before another + # hit is made against it. The API for doing so mimics the options from +url_for+ and friends: # # class WeblogController < ActionController::Base # def update # List.update(params[:list][:id], params[:list]) - # expire_page :action => "show", :id => params[:list][:id] - # redirect_to :action => "show", :id => params[:list][:id] + # expire_page action: 'show', id: params[:list][:id] + # redirect_to action: 'show', id: params[:list][:id] # end # end # - # Additionally, you can expire caches using Sweepers that act on changes in the model to determine when a cache is supposed to be - # expired. + # Additionally, you can expire caches using Sweepers that act on changes in + # the model to determine when a cache is supposed to be expired. module Pages extend ActiveSupport::Concern included do - # The cache directory should be the document root for the web server and is set using Base.page_cache_directory = "/document/root". - # For Rails, this directory has already been set to Rails.public_path (which is usually set to Rails.root + "/public"). Changing - # this setting can be useful to avoid naming conflicts with files in public/, but doing so will likely require configuring your - # web server to look in the new location for cached files. + # The cache directory should be the document root for the web server and is + # set using Base.page_cache_directory = "/document/root". For Rails, + # this directory has already been set to Rails.public_path (which is usually + # set to Rails.root + "/public"). Changing this setting can be useful + # to avoid naming conflicts with files in public/, but doing so will + # likely require configuring your web server to look in the new location for + # cached files. class_attribute :page_cache_directory self.page_cache_directory ||= '' - # Most Rails requests do not have an extension, such as /weblog/new. In these cases, the page caching mechanism will add one in - # order to make it easy for the cached files to be picked up properly by the web server. By default, this cache extension is .html. - # If you want something else, like .php or .shtml, just set Base.page_cache_extension. In cases where a request already has an - # extension, such as .xml or .rss, page caching will not add an extension. This allows it to work well with RESTful apps. + # Most Rails requests do not have an extension, such as /weblog/new. + # In these cases, the page caching mechanism will add one in order to make it + # easy for the cached files to be picked up properly by the web server. By + # default, this cache extension is .html. If you want something else, + # like .php or .shtml, just set Base.page_cache_extension. + # In cases where a request already has an extension, such as .xml + # or .rss, page caching will not add an extension. This allows it + # to work well with RESTful apps. class_attribute :page_cache_extension self.page_cache_extension ||= '.html' - # The compression used for gzip. If false (default), the page is not compressed. - # If can be a symbol showing the ZLib compression method, for example, :best_compression - # or :best_speed or an integer configuring the compression level. + # The compression used for gzip. If +false+ (default), the page is not compressed. + # If can be a symbol showing the ZLib compression method, for example, :best_compression + # or :best_speed or an integer configuring the compression level. class_attribute :page_cache_compression self.page_cache_compression ||= false end @@ -62,7 +74,7 @@ module ActionController #:nodoc: module ClassMethods # Expires the page that was cached with the +path+ as a key. # - # expire_page "/lists/show" + # expire_page '/lists/show' def expire_page(path) return unless perform_caching path = page_cache_path(path) @@ -75,7 +87,7 @@ module ActionController #:nodoc: # Manually cache the +content+ in the key determined by +path+. # - # cache_page "I'm the cached content", "/lists/show" + # cache_page "I'm the cached content", '/lists/show' def cache_page(content, path, extension = nil, gzip = Zlib::BEST_COMPRESSION) return unless perform_caching path = page_cache_path(path, extension) @@ -90,19 +102,19 @@ module ActionController #:nodoc: end # Caches the +actions+ using the page-caching approach that'll store - # the cache in a path within the page_cache_directory that + # the cache in a path within the +page_cache_directory+ that # matches the triggering url. # - # You can also pass a :gzip option to override the class configuration one. + # You can also pass a :gzip option to override the class configuration one. # # # cache the index action # caches_page :index # # # cache the index action except for JSON requests - # caches_page :index, :if => Proc.new { !request.format.json? } + # caches_page :index, if: Proc.new { !request.format.json? } # # # don't gzip images - # caches_page :image, :gzip => false + # caches_page :image, gzip: false def caches_page(*actions) return unless perform_caching options = actions.extract_options! @@ -144,7 +156,7 @@ module ActionController #:nodoc: # Expires the page that was cached with the +options+ as a key. # - # expire_page :controller => "lists", :action => "show" + # expire_page controller: 'lists', action: 'show' def expire_page(options = {}) return unless self.class.perform_caching @@ -161,10 +173,11 @@ module ActionController #:nodoc: end end - # Manually cache the +content+ in the key determined by +options+. If no content is provided, the contents of response.body is used. - # If no options are provided, the url of the current request being handled is used. + # Manually cache the +content+ in the key determined by +options+. If no content is provided, + # the contents of response.body is used. If no options are provided, the url of the current + # request being handled is used. # - # cache_page "I'm the cached content", :controller => "lists", :action => "show" + # cache_page "I'm the cached content", controller: 'lists', action: 'show' def cache_page(content = nil, options = nil, gzip = Zlib::BEST_COMPRESSION) return unless self.class.perform_caching && caching_allowed? diff --git a/actionpack/lib/action_controller/caching/sweeping.rb b/actionpack/lib/action_controller/caching/sweeping.rb index 271d5f06b8..317ac74b40 100644 --- a/actionpack/lib/action_controller/caching/sweeping.rb +++ b/actionpack/lib/action_controller/caching/sweeping.rb @@ -1,38 +1,41 @@ -module ActionController #:nodoc: +module ActionController module Caching - # Sweepers are the terminators of the caching world and responsible for expiring caches when Active Record objects change. - # They do this by being half-observers, half-filters and implementing callbacks for both roles. A Sweeper example: + # Sweepers are the terminators of the caching world and responsible for expiring + # caches when Active Record objects change. They do this by being half-observers, + # half-filters and implementing callbacks for both roles. # # class ListSweeper < ActionController::Caching::Sweeper # observe List, Item # # def after_save(record) # list = record.is_a?(List) ? record : record.list - # expire_page(:controller => "lists", :action => %w( show public feed ), :id => list.id) - # expire_action(:controller => "lists", :action => "all") - # list.shares.each { |share| expire_page(:controller => "lists", :action => "show", :id => share.url_key) } + # expire_page(controller: 'lists', action: %w( show public feed ), id: list.id) + # expire_action(controller: 'lists', action: 'all') + # list.shares.each { |share| expire_page(controller: 'lists', action: 'show', id: share.url_key) } # end # end # - # The sweeper is assigned in the controllers that wish to have its job performed using the cache_sweeper class method: + # The sweeper is assigned in the controllers that wish to have its job performed using + # the +cache_sweeper+ class method: # # class ListsController < ApplicationController # caches_action :index, :show, :public, :feed - # cache_sweeper :list_sweeper, :only => [ :edit, :destroy, :share ] + # cache_sweeper :list_sweeper, only: [ :edit, :destroy, :share ] # end # # In the example above, four actions are cached and three actions are responsible for expiring those caches. # - # You can also name an explicit class in the declaration of a sweeper, which is needed if the sweeper is in a module: + # You can also name an explicit class in the declaration of a sweeper, which is needed + # if the sweeper is in a module: # # class ListsController < ApplicationController # caches_action :index, :show, :public, :feed - # cache_sweeper OpenBar::Sweeper, :only => [ :edit, :destroy, :share ] + # cache_sweeper OpenBar::Sweeper, only: [ :edit, :destroy, :share ] # end module Sweeping extend ActiveSupport::Concern - module ClassMethods #:nodoc: + module ClassMethods # :nodoc: def cache_sweeper(*sweepers) configuration = sweepers.extract_options! @@ -51,7 +54,7 @@ module ActionController #:nodoc: end if defined?(ActiveRecord) and defined?(ActiveRecord::Observer) - class Sweeper < ActiveRecord::Observer #:nodoc: + class Sweeper < ActiveRecord::Observer # :nodoc: attr_accessor :controller def initialize(*args)