README

VersionCache
===========

A Ruby on rails (v2.1.0) plugin that provides additional caching features.
Version caching is similar to action caching but it solves one major problem.
It solves the problem of having to expire your cached stuff via the provided rails methods. Instead, it relies on versions.
For example, say we have a PostsController and a corresponding Post model and we need to cache the show action of the PostsController.

For generating a response to the request http://localhost:3000/posts/1 the following will happen
1. Check the version of Post with id 1 from cache store with the key "Post_1"
2. if not found then the version is assumed to be 0
3. The cache store is queried using a key that's composed of the request's url + the version.
4. If the cache hits then the response is fetched from the cache but if it misses then the response is generated normally and stored in the cache.

However there needs to be some means to change the versions. This is achieved using observers. A cache observer will observe the model and change its version upon creation, updating, or deletion.

The first time a request is made to http://localhost:3000/posts/1, the page is stored in the cache store with the key "localhost.:posts/1:0". Subsequent requests will be served from cache until an update is made to post 1 which will cause the version to become 1.

One more feature of the plugin is time caching.


Introducing the plugin blog entry
=================================
http://humanzz.spaces.live.com/blog/cns!82322F9506CB0449!713.entry


Setup
=====

	ruby script/plugin install git://github.com/humanzz/version_cache.git

After installing the version_cache plugin you'll need to do the following
1. Generate the version_cache_observer using the supplied generator as follows
	ruby script/generate version_cache_observer ObserverName Model1 Model2

	Example:
		ruby script/generate version_cache_observer Cache Post Topic

		This will create:
    	Observer:      app/models/cache_observer.rb
      The cache_observer will observe Topic and Post models

2. Register the observer in your environment
	config.active_record.observers ObserverName


Usage
=====

* To version cache an action put the following line in the controller

class ItemsController < ApplicationController
	.
	version_cache Item, :expiry => 20
	.
	.
end
	
	Item: model whose version is used
	expiry: 0 means don't expire, any other number is taken to be a maximum time to cache (in minutes)
	
if used without declaring an :action option then the show action is the one that'll be used.

* To time cache an action

class WelcomeController < ApplicationController
  .
  .
	time_cache :index => {:expiry => 20} #cache for 20 minutes
	time_cache :show => {:expiry => 5, :browser_cache => true}
	.
	.
end
	:expiry is the amount of time in minutes
	:browser_cache => (true|false) which causes the insertion of expires and cache-control headers
	so that the browser can serve the page from its local cache without even consulting your
	application

* An additional feature is that some models updates should not only change their versions, but
  versions of other models as well.
  For example, we have ItemsController and Item model and User model where an item belongs to a user,
  and we want the user's version to change when the item's vesion change. We do the following
  
class ItemsController < ApplicationController
  .
  version_cache Item
  .
  .
end

class Item < ActiveRecord::Base
  belongs_to :user
  
  has_cache_associates :user
end
	
Now whenever an item is created, updated or destroyed not only will its version be incremented but
it's user's version as well.
	
	
Other convenience methods
=========================
These are methods that can be overriden in your controllers to provide some effect

* version_cache_model_id

Consider the case of the url http://localhost:3000/users/59/profile. If you want to cache that page based on the user model's version,
then you should do the following

class ProfilesController < ApplicationController
	.
	version_cache User
	.
	
	def version_cache_model_id
		params[:user_id]
	end
end

* version_cache_key_part

This can be used if we want to cache multiple versions of the same
page....this function should return a string that determines which version is this page
for example in a controller that uses version or time caching for its show action, assume that the show action shows 2 versions to 2 types of users

class WelcomeController < ApplicationController
  .
  .
	time_cache :index => {:expiry => 20}
	.
	.
	def version_cache_key_part
	  current_user.type_1? ? "one" : "two"
	end
end


Copyright (c) 2008 humanzz (Ahmed Sobhi), released under the MIT license