gistfile1.html

merb-cache was rewritten with a few goals in mind:
	<ol>
	<li>make it modulular</li>
		<li>define a public <span class="caps">API</span></li>
		<li>do the heavy lifting on key generation</li>
		<li>100% thread-safe</li>
		<li>work with multiple caching layers through the same <span class="caps">API</span></li>
		<li>keep it hackable</li>
	</ol>


	<h3>Stores</h3>


	<p>First and foremost, cache stores have been seperated into two families: fundamental stores and strategy stores. A fundamental store is any store that interacts directly with the persistence layer. The <b>FileStore</b>, for example, is a fundamental store that reads &#38; writes cache entries to the file system. <b>MemcachedStore</b> is also a fundamental store. They have almost identical functionality to the existing caching technique, only they implement a common <span class="caps">API</span> defined by <b>AbstractStore</b>.</p>


	<p>The strategy store is the new kid on the block. A strategy store wraps one or more fundamental stores, acting as a middle man between caching requests. For example, if you need to save memory on your Memcache server, you could wrap your <b>MemcachedStore</b> with a <b>GzipStore</b>. This would automatically compress the cached data when put into the cache, and decompressed on the way out. You can even wrap strategy caches with other strategy caches. In the last example, if you key was comprised of sensitive information, like a <span class="caps">SSN</span>, you might want to encrypt the key before storage. Wrapping your <b>GzipStore</b> in a <b>SHA1Store</b> would take care of that for you.</p>


	<h3>Public <span class="caps">API</span></h3>


	<p>The <b>AbstractStore</b> class defines 9 methods as the <span class="caps">API</span>:</p>


	<ol>
	<li><b>writable?(key, parameters = {}, conditions = {})</b></li>
		<li><b>exists?(key, parameters = {})</b></li>
		<li><b>read(key, parameters = {})</b></li>
		<li><b>write(key, data = nil, parameters = {}, conditions = {})</b></li>
		<li><b>write_all(key, data = nil, parameters = {}, conditions = {})</b></li>
		<li><b>fetch(key, parameters = {}, conditions = {}, &#38;blk)</b></li>
		<li><b>delete(key, parameters = {})</b></li>
		<li><b>delete_all</b></li>
		<li><b>delete_all!</b></li>
	</ol>


	<p><b>AbstractStrategyStore</b> implements all of these with the exception of <b>delete_all</b>. If a strategy store can guarantee that calling <b>delete_all</b> on it&#8217;s wrapped store(s) will only delete entries populated by the strategy store, it may define the safe version of <b>delete_all</b>. However, this is usually not the case, hence <b>delete_all</b> is not part of the public <span class="caps">API</span> for <b>AbstractStrategyStore</b>.</p>


	<p>A more detailed documentation on each method can be found here: <span class="caps">LINK</span></p>


	<h3>Less Talk, More Code</h3>


	<p>So here&#8217;s how you can setup and use merb-cache in your merb app:</p>


	<h4>config/environments/development.rb</h4>


<pre>
<code>
  # create a fundamental memcache store named :memcache for localhost
  Merb::Cache.setup(:memcache, Merb::Cache::MemcachedStore, {
    :namespace =&gt; "my_app",
    :servers =&gt; ["127.0.0.1:11211"]
  }

  # a default FileStore
  Merb::Cache.setup(Merb::Cache::FileStore)

  # another FileStore
  Merb::Cache.setup(:tmp_cache, Merb::Cache::FileStore, :dir =&gt; "/tmp")
</code>
</pre>

	<p>Now lets use these in a model:</p>


	<h4>app/models/tag.rb</h4>


<pre>
<code>
  class Tag
    #...

    def find(parameters = {})
      # poor man's identity map

      if Merb::Cache[:memcached].exists?("tags", parameters)
        Merb::Cache[:memcached].read("tags", parameters)
      else
        returning(super(parameters)) do |results|
          Merb::Cache[:memcached].write("tags", results, parameters)
        end
      end
    end

    def popularity_rating
      # lets keep the popularity rating cached for 30 seconds
      # merb-cache will create a key from the model's id &#38; the interval parameter

      Merb::Cache[:memcache].fetch(self.id, :interval =&gt; Time.now.to_i / 30) do
        self.run_long_popularity_rating_query
      end
    end
  end
</code>
</pre>

	<p>Or, if you want to use memcache&#8217;s built in expire option:</p>


<pre>
<code>
  # expire a cache entry for "bar" (identified by the key "foo" and
  # parameters {:baz =&gt; :bay}) in two hours
  Merb::Cache[:memcache].write("foo", "bar", {:baz =&gt; :bay}, :expire_in =&gt; 2.hours)

  # this will fail, because FileStore cannot expire cache entries
  Merb::Cache[:default].write("foo", "bar", {:baz =&gt; :bay}, :expire_in =&gt; 2.hours)

  # writing to the FileStore will fail, but the MemcachedStore will succeed
  Merb::Cache[:default, :memcache].write("foo", "bar", {:baz =&gt; :bay}, :expire_in =&gt; 2.hours)

  # this will fail
  Merb::Cache[:default, :memcached].write_all("foo", "bar", {:baz =&gt; :bay}, :expire_in =&gt; 2.hours)
</code>
</pre>

	<h3>Strategy Stores</h3>


	<p>Setting up strategy stores is very similar to fundamental stores:</p>


	<h4>config/environments/development.rb</h4>


<pre>
<code>
  # wraps the :memcache store we setup earlier
  Merb::Cache.setup(:zipped, Merb::Cache::GzipStore[:memcache])

  # wrap a strategy store
  Merb::Cache.setup(:sha_and_zip, Merb::Cache::SHA1Store[:zipped])

  # you can even use unnamed fundamental stores
  Merb::Cache.setup(:zipped_images, Merb::Cache::GzipStore[Merb::Cache::FileStore],
                    :dir =&gt; Merb.root / "public" / "images")

  # or a combination or strategy &#38; fundamental stores
  module Merb::Cache #makes things a bit shorter

    setup(:secured, SHA1Store[GzipStore[FileStore], FileStore],
          :dir =&gt; Merb.root / "private")
  end
</code>
</pre>

	<p>You can use these strategy stores exactly like fundamental stores in your app code.</p>


	<h3>Action &#38; Page Caching</h3>


	<p>Action &#38; page caching have been implemented in strategy stores. So instead of manually specifying which type of caching you want for each action, you simply ask merb-cache to cache your action, and merb-cache will use the fastest available cache.</p>


	<p>First, let&#8217;s setup our page &#38; action stores:</p>


	<h4>config/environments/development.rb</h4>


<pre>
<code>
  # the order that stores are setup is important
  # faster stores should be setup first

  # page cache to the public dir
  Merb::Cache.setup(:page_store, Merb::Cache::PageCache[FileStore],
                    :dir =&gt; Merb.root / "public")

  # action cache to memcache
  Merb::Cache.setup(:action_store, Merb::Cache::ActionCache[:sha_and_zip])
</code>
</pre>

	<p>And now in our controller:</p>


	<h4>app/controllers/tags.rb</h4>


<pre>
<code>
  class Tags &amp;lt; Merb::Controller

    # index &#38; show will be page cached to the public dir. The index
    # action has no parameters, and the show parameter's are part of
    # the query string, making them both page-cache'able
    cache :index, :show

    def index
      render
    end

    # merb-cache works automatically with merb-action-args
    def show(id)
      dispay Tag.first(:id =&gt; id)
    end

    # action caches if there are POST parameters
    cache :graph, :params =&gt; [:tags, :start_date, :end_date, :interval]

    def graph
      @interval = params[:interval]
      display Tag.all(:id.in =&gt; params[:tags], :start_date =&gt; params[:start_date],
                      :end_date =&gt; params[:end_date])
    end

    # works with :if/:unless conditions, but action caches
    cache :home, :if =&gt; :logged_in?

    def home
      display Tag.all(:user =&gt; current_user)
    end

    # or you can manually specify a store
    cache :short, :store =&gt; :action_store

    def short(id)
      display Tag.first(id)
    end
  end
</code>
</pre>

	<h3>Keeping A Hot Cache &#38; Eager Caching</h3>


	<p>Keeping your cache current is a problem for a lot of web apps.  The new merb-cache gives you a few tools to keep your cache from getting stale.  The eager_cache method allows you to create triggers for updating cache content when it becomes stale.  It uses the run_later method, which means the cached content is replaced after the response is served.</p>


	<h4>app/controllers/articles.rb</h4>


<pre>
<code>
  class Articles &amp;lt; Merb::Controller

    # start by page caching the index
    cache :index

    # simple action, nothing fancy
    def index(page = 1)
      display Acticle.paginate(:page =&gt; page)
    end

    # lets automatically cache the next page, if the user requests
    # anything other than the first page
    eager_cache(:index, :unless =&gt; :main_page?) do |controller|
      controller.params[:page] = (controller.params[:page].to_i) + 1
    end

    def main_page?
      params[:page].nil? || params[:page].to_i == 1
    end

    # or, we can specify eager caching in the action itself
    def index(page = 1)
      unless page == 1
        eager_cache :index do |controller|
          controller.params[:page] = page + 1
        end
      end

      display Acticle.paginate(:page =&gt; page)
    end
  end
</code>
</pre>