ultracache 0.1.0

data/.gitignore

@@ -0,0 +1,2 @@
+pkg/*
+*.gem

data/.rvmrc

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+
+# This is an RVM Project .rvmrc file, used to automatically load the ruby
+# development environment upon cd'ing into the directory
+
+# First we specify our desired <ruby>[@<gemset>], the @gemset name is optional.
+environment_id="ruby-1.9.3-p0@ultracache"
+
+#
+# Uncomment following line if you want options to be set only for given project.
+#
+# PROJECT_JRUBY_OPTS=( --1.9 )
+#
+# The variable PROJECT_JRUBY_OPTS requires the following to be run in shell:
+#
+#    chmod +x ${rvm_path}/hooks/after_use_jruby_opts
+#
+
+#
+# First we attempt to load the desired environment directly from the environment
+# file. This is very fast and efficient compared to running through the entire
+# CLI and selector. If you want feedback on which environment was used then
+# insert the word 'use' after --create as this triggers verbose mode.
+#
+if [[ -d "${rvm_path:-$HOME/.rvm}/environments" \
+  && -s "${rvm_path:-$HOME/.rvm}/environments/$environment_id" ]]
+then
+  \. "${rvm_path:-$HOME/.rvm}/environments/$environment_id"
+
+  if [[ -s "${rvm_path:-$HOME/.rvm}/hooks/after_use" ]]
+  then
+    . "${rvm_path:-$HOME/.rvm}/hooks/after_use"
+  fi
+else
+  # If the environment file has not yet been created, use the RVM CLI to select.
+  if ! rvm --create  "$environment_id"
+  then
+    echo "Failed to create RVM environment '${environment_id}'."
+    return 1
+  fi
+fi
+
+#
+# If you use an RVM gemset file to install a list of gems (*.gems), you can have
+# it be automatically loaded. Uncomment the following and adjust the filename if
+# necessary.
+#
+# filename=".gems"
+# if [[ -s "$filename" ]]
+# then
+#   rvm gemset import "$filename" | grep -v already | grep -v listed | grep -v complete | sed '/^$/d'
+# fi
+
+# If you use bundler, this might be useful to you:
+# if [[ -s Gemfile ]] && ! command -v bundle >/dev/null
+# then
+#   printf "The rubygem 'bundler' is not installed. Installing it now.\n"
+#   gem install bundler
+# fi
+# if [[ -s Gemfile ]] && command -v bundle
+# then
+#   bundle install
+# fi
+
+if [[ $- == *i* ]] # check for interactive shells
+then
+    echo "Using: $(tput setaf 2)$GEM_HOME$(tput sgr0)" # show the user the ruby and gemset they are using in green
+else 
+	echo "Using: $GEM_HOME" # don't use colors in interactive shells
+fi
+

data/Gemfile

@@ -0,0 +1,3 @@
+source 'http://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,55 @@
+PATH
+  remote: .
+  specs:
+    ultracache (0.1.0)
+      activemodel (~> 3.0)
+      activesupport (~> 3.0)
+      json
+      redis (~> 2.2)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.1.3)
+      activesupport (= 3.1.3)
+      builder (~> 3.0.0)
+      i18n (~> 0.6)
+    activesupport (3.1.3)
+      multi_json (~> 1.0)
+    bson (1.5.2)
+    bson_ext (1.5.2)
+      bson (= 1.5.2)
+    builder (3.0.0)
+    diff-lcs (1.1.3)
+    i18n (0.6.0)
+    json (1.6.4)
+    metaclass (0.0.1)
+    mocha (0.10.0)
+      metaclass (~> 0.0.1)
+    mongo (1.5.2)
+      bson (= 1.5.2)
+    mongoid (2.4.0)
+      activemodel (~> 3.1)
+      mongo (~> 1.3)
+      tzinfo (~> 0.3.22)
+    multi_json (1.0.4)
+    redis (2.2.2)
+    rspec (2.7.0)
+      rspec-core (~> 2.7.0)
+      rspec-expectations (~> 2.7.0)
+      rspec-mocks (~> 2.7.0)
+    rspec-core (2.7.1)
+    rspec-expectations (2.7.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.7.0)
+    tzinfo (0.3.31)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bson_ext
+  mocha
+  mongoid
+  rspec (~> 2.6)
+  ultracache!

data/README.md

@@ -0,0 +1,130 @@
+Ultracache
+==========
+
+Ultracache provides model-level interfaces for better abstraction of
+your cached data. You can organize and store/fetch cached data easily
+through the provided interfaces. You can boost up the response time of
+your actions through appropriate caching of persisted data.
+
+Ultracache uses a conventional key-value store as its backend. Currently
+it only supports Redis, but we are planning to include other storages
+like Memcached into our feature set.
+
+Installation
+------------
+
+Add Ultracache to your `Gemfile`.
+
+    gem 'ultracache'
+
+Or, install Ultracache manually with Rubygems.
+
+
+Configurations
+--------------
+
+Generate an initializer for Ultracache in
+`config/initializers/ultracache.rb`.
+
+    # config/initializers/ultracache.rb
+
+    Ultracache.config do |config|
+      config.storage = Ultracache::Storage::Redis.new(:urls => ['localhost'])
+      config.serializer = Ultracache::Serializer::JsonSerializer.new
+    end
+
+Usage
+-----
+
+Ultracache associates cache with your model objects. Model objects can
+have cached attributes or queues of other cached models. You can decide
+appropriate method for caching which meets your requirements.
+
+### Cached Attributes
+
+You need to mixin `Ultracache::Cached` module into your model objects to
+which you want to associate your cache.
+
+Cached attributes is the simplest form to associate caches with your
+models. Here's an example:
+
+    class Person
+      include Ultracache::Cached
+
+      has_cached_attribute :cached_colleagues do |obj|
+        obj.colleagues.as_json(:with_contact => true)
+      end
+    end
+
+Keep in mind that return value of presented block is serialized to
+a string by the serailizer specified in configurations. If block is not
+presented, Ultracache tries to serialize the object with `as_json`
+method.
+
+    class Person
+      include Ultracache::Cached
+
+      has_cached_attribute :serialized_string # Objects are serialized with Person#as_json
+    end
+
+Cached attributes are useful when cost to generate the desired data is
+high, like JSON serializations. Once we have noticed severe performance
+degradation caused by plain JSON serializations.
+
+### Cached Queues
+
+Cached queue is suitable when your actions require collection of
+objects, like the most index actions. Like `has_many` relationship of
+ActiveRecord, cached queues are made from a relationship of two model
+classes.
+
+    class Person
+      include Ultracache::Cached
+
+      has_cached_queue :notifications
+    end
+
+    class Notification
+      include Ultracache::Cached
+
+      cached_queue_in :person do |obj|
+        {
+          :id => obj.id,
+          :content => obj.content
+        }
+      end
+    end
+
+Cached queues are especially useful when cost to fetch additional data
+from your persistent storage is significantly high. Queuries including
+referenced relationships of MongoDB or heavy join operations fit for
+this type of concerns.
+
+    p = Person.find params[:id]
+    notifications = p.notifications
+
+Note that entries in queues are stored as string. If you want to fetch
+or modify part of the model objects, you need to deserialize them. 
+
+    p = Person.find params[:id]
+    notifications = p.notifications :deserialized => true
+    
+    notifications.first['content'] # Content cached in your queue previously
+
+### Keeping them with Integrity
+
+Lifecycle of caches generated by Ultracache are synchronized with it of
+model objects.  Ultracache adds `save_cache`, `update_cache`,
+`destroy_cache` methods to models which include Ultracache::Cached.
+These methods are registered as ActiveModel callbacks semantically
+corresponding to each method.
+
+By default, contents of cached attributes are updated along with status
+of model objects they belong to. On the other hand, you can decide
+whether entries in cached queues are updated or not.
+
+Further Documentations
+----------------------
+
+Refer comments in source files for more detailed information. We are
+preparing detailed documentations which will be published soon.

data/Rakefile

@@ -0,0 +1,20 @@
+require 'bundler'
+require 'rspec/core/rake_task'
+
+desc 'Default: run specs.'
+task :default => :spec
+
+desc "Run specs"
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = "./spec/**/*_spec.rb" # don't need this, it's default.
+  # Put spec opts in a file named .rspec in root
+end
+
+desc "Generate code coverage"
+RSpec::Core::RakeTask.new(:coverage) do |t|
+  t.pattern = "./spec/**/*_spec.rb" # don't need this, it's default.
+  t.rcov = true
+  t.rcov_opts = ['--exclude', 'spec']
+end
+
+Bundler::GemHelper.install_tasks

data/lib/ultracache.rb

@@ -0,0 +1,29 @@
+require 'active_model'
+require 'active_support/core_ext'
+require 'json'
+
+require 'ultracache/configurations'
+require 'ultracache/storage/redis'
+require 'ultracache/serializer/base'
+require 'ultracache/serializer/json_serializer'
+require 'ultracache/macro'
+require 'ultracache/cached'
+require 'ultracache/relationships'
+require 'ultracache/relationship'
+require 'ultracache/relationship/belongs_as_cached_queue'
+require 'ultracache/relationship/has_cached_queue'
+require 'ultracache/relationship/has_cached_attribute'
+
+if defined?(Rails)
+  require "ultracache/railtie"
+end
+
+module Ultracache
+  class << self
+    def config
+      yield Configurations
+    end
+
+    alias :configuration :config
+  end
+end

data/lib/ultracache/cached.rb

@@ -0,0 +1,102 @@
+module Ultracache
+  # This class should be included to model classes related to cache. It adds
+  # primitive methods, attributes and callbacks required for caching.
+  #
+  # Example:
+  #
+  #     class Person < ActiveRecord::Base
+  #       include Ultracache::Cached
+  #
+  #       # Cache definitions ...
+  #     end
+  #
+  # Including this class adds a Relationships object which is stored into
+  # Ultracache::Configurations. Every relationship added to the class is
+  # represented by a Relationship object inside Relationships object regarding
+  # the class.
+  module Cached
+    extend ActiveSupport::Concern
+
+    include Macro
+
+    included do
+      extend ActiveModel::Callbacks
+      define_model_callbacks :save, :destroy
+
+      after_create :save_cache
+      after_update :update_cache
+      after_destroy :destroy_cache
+
+      unless Ultracache::Configurations.find_relationships(self, :strict => true)
+        Ultracache::Configurations.add_relationships(self)
+      end
+    end
+
+    # Read cache from storage. Cache to read is specified by the `name` parameter.
+    # Relationship object should exist in Relationships related to the class.
+    def read_cache(name, options={})
+      relationship = self.class.relationships.find(name.to_sym)
+      strings = relationship.read_cache(self, options)
+
+      if options[:deserialized]
+        return strings.map do |str|
+          Ultracache::Configurations.serializer.deserialize str
+        end
+      else
+        return strings
+      end
+    end
+
+    # Save caches of all relationships assigned to the class. If `:only` option is
+    # provided, only caches specified in the option are saved.
+    #
+    # Example
+    #
+    #     p = Person.find params[:id]
+    #     p.save_cache # Saves all caches related to Person class
+    #     p.save_cache :only => [:cached_name] # Saves cached_name only
+    #
+    # `save_cache` is registered as `after_save` callback for ActiveModel classes
+    # which mixin `Ultracache::Cached`.
+    def save_cache(options = {})
+      target = self.class.relationships.keys
+      target &= options[:only] if options[:only]
+
+      target.each do |name|
+        self.class.relationships[name].save_cache(self)
+      end
+    end
+
+    # Remove all cache related to the object from the storage. `destroy_cache` is
+    # registered as `after_destroy` callback for ActiveModel classes which mixin
+    # `Ultracache::Cached`.
+    def destroy_cache
+      self.class.relationships.each do |name, relationship|
+        relationship.destroy_cache(self)
+      end
+    end
+
+    # Updates all cache related to the class, like `save_cache` does. `:only`
+    # option also can be used for this method. This method is registered as
+    # `after_update` callback.
+    def update_cache(options = {})
+      target = self.class.relationships.keys
+      target &= options[:only] if options[:only]
+
+      target.each do |name|
+        self.class.relationships[name].update_cache(self)
+      end
+    end
+
+    module ClassMethods
+      # Finds all Relationship objects associated with the class. The relationships
+      # include cache associations defined in parent classes of the caller class.
+      # A new Relationships object is created as return value of this method.
+      def relationships(options = {})
+        rs = Ultracache::Configurations.find_relationships(self, options)
+        return Ultracache::Configurations.add_relationships(self) unless rs
+        rs
+      end
+    end
+  end
+end

data/lib/ultracache/configurations.rb

@@ -0,0 +1,79 @@
+module Ultracache
+  # This class contains configurations for Ultracache. Proper configurations
+  # should be set before caching objects and attributes you need.
+  #
+  # Put configurations for your Rails project into initializer:
+  #
+  #     # config/initializers/ultracache.rb
+  #     Ultracache.config do |config|
+  #       config.storage = Ultracache::Storage::Redis.new
+  #       config.serializer = Ultracache::Serializer::JsonSerializer.new
+  #     end
+  #
+  # Configurable attributes include `storage` and `serializer` for now.
+  class Configurations
+    class << self
+      # Setter for storage handler of Ultracache.
+      def storage=(storage)
+        @storage = storage
+      end
+
+      # Getter for storage handler of Ultracache.
+      def storage
+        @storage
+      end
+
+      # Setter for serializer of Ultracache.
+      # `Ultracache::Serializer::JsonSerializer` is set as default value.
+      def serializer=(serializer)
+        @serializer = serializer
+      end
+
+      # Getter for serializer of Ultracache.
+      def serializer
+        @serializer
+      end
+
+      def relationships_container
+        @relationships ||= Hash.new
+      end
+
+      def add_relationships(klass)
+        unless relationships_container[klass]
+          rs = Relationships.new(klass)
+          relationships_container[klass] = rs
+          rs
+        else
+          nil
+        end
+      end
+
+      def find_relationships(klass, options = {})
+        rs_set = []
+
+        relationships_container.each do |k, rs|
+          if klass == k
+            return rs if options[:strict]
+            rs_set << rs
+          end
+        end
+
+        return nil if options[:strict]
+
+        relationships_container.each do |k, rs|
+          if klass <= k
+            rs_set << rs
+          end
+        end
+
+        if rs_set.empty?
+          nil
+        else
+          rs_set.inject(Relationships.new(klass)) do |base, rs|
+            base.merge(rs)
+          end
+        end
+      end
+    end
+  end
+end