mongo_cache_store 0.2.0 → 0.2.1

data/README.rdoc

@@ -0,0 +1,159 @@
+= MongoCacheStore
+
+A MongoDB cache store for ActiveSupport 3
+
+== Description
+
+MongoCacheStore uses pluggable backends to expose MongoDB 
+as a cache store to ActiveSupport applications.  Each backend 
+allows the application to customize how the cache operates.  
+Support is available for standard, capped and TTL collections.
+
+*WARNING* This gem is in the early stages of development and 
+should be treated as such.  Checking the version of the gem will 
+help with what could be many changes to the backends, options, etc...
+
+While in beta, the major version will always be 0.  The minor version 
+will be increased for anything that breaks the current API.  The patch 
+version will be increased for all changes within a minor revision that 
+add to or fix the current release without changing how the gem is 
+configured or used. 
+
+== Initialize the cache
+
+=== Usage
+
+    config.cache_store = :mongo_cache_store, :TTL, :db => Mongo::DB.new('db_name',Mongo::Connection.new)
+    config.cache_store = :mongo_cache_store, :Standard, :db_name => 'db_name', :connection => Mongo::Connection.new, :serialize => :on_fail
+
+=== Attributes  
+ 
+[+backend+ - Symbol representing the backend the cache should use] 
+    :TTL:: ActiveSupport::Cache::MongoCacheStore::Backend::TTL
+    :Standard:: ActiveSupport::Cache::MongoCacheStore::Backend::Standard
+    :MultiTTL:: ActiveSupport::Cache::MongoCacheStore::Backend::MultiTTL
+    :Capped:: ActiveSupport::Cache::MongoCacheStore::Backend::Capped
+
+ [+options+ - Options for ActiveSupport::Cache and the backend] 
+    Core options are listed here.  See each backend for a list of additional optons. 
+    [+:db+ - A Mongo::DB instance.]
+    [+:db_name+ - Name of database to create if no 'db' is given.] 
+    [+:connection+ - A Mongo::Connection instance. Only used if no 'db' is given.] 
+    [+:serialize+ - *:always* | :on_fail | :never]
+        [+:always+ - (default) - Serialize all entries]
+            *NOTE* Without serialization class structures and instances that cannot 
+            be converted to a native MongoDB type will not be stored.  Also, 
+            without serialization MongoDB converts all symbols to strings.  
+            Therefore a hash with symbols as keys will have strings as keys when read. 
+         [+:on_fail+ - Serialize if native format fails]
+            Try to save the entry in a native MongoDB format.  If that fails, 
+            then serialize the entry. 
+        [+:never+ - Never serialize]
+            Only save the entry if it can be saved natively by MongoDB.
+
+
+== Backends
+
+== TTL
+
+TTL backend for MongoCacheStore
+
+=== Description
+  
+Entries are kept in a namespaced TTL collection that will 
+automatically flush any entries as they pass their expiration 
+time. This keeps the size of the cache in check over time. 
+<b>Requires MongoDB 2.0 or higher</b>
+
+=== Additional Options
+
+No additional options at this time
+
+
+== Standard 
+Standard backend for MongoCacheStore
+ 
+=== Description
+
+Entreis are kept in a namespaced MongoDB collection. In a standard 
+collection entries are only flushed from the collection with an 
+explicit delete call or if auto_flush is enabled.  If auto_flush is 
+enabled the cache will flush all expired entries when auto\_flush\_threshold 
+is reached.  The threshold is based on a set number of cache instance writes. 
+
+=== Additional Options  
+ 
+The following options can be added to a MongoCacheStore constructor
+[+options+ - Standard backend options] 
+    To see a list of core options see MongoCacheStore
+    [+:auto_flush+ - *true* | false]
+        Default: true
+        
+        If auto_flush is enabled the cache will flush all 
+        expired entries when auto\_flush\_threshold
+        is reached.
+    [+:auto_flush_threshold+ - *10_000*] 
+        Default: 10_000
+
+        A number representing the number of writes the when the cache 
+        should preform before flushing expired entries.
+
+
+== MultiTTL 
+
+MultiTTL backend for MongoCacheStore
+ 
+=== Description
+
+Entries are stored in multiple namespaced TTL collections. 
+A namespaced TTL collection is created for each unique expiration time.  
+For example all entries with an expiration time of 300 seconds will be 
+kept in the same collection while entries with a 900 second expiration 
+time will be kept in another.  This requires the use of a *key index* 
+collection that keeps track of which TTL collection a entry resides in. 
+
+==== Downsides
+* Cache set operations require 2 MongoDB write calls.  
+  One for the key index, one for the TTL collection. 
+  (unless *use_index* is false, see below)
+* Cache read operations will require 1 or 2 MongoDB calls 
+  depending on whether the 'expires_in' option is set for the read.
+
+==== Benefits (future)
+* Ability to flush cache based on expire time (TODO)
+
+
+=== Additional Options  
+  
+The following options can be added to a MongoCacheStore constructor
+
+[+options+ - MultiTTL backend options] 
+    To see a list of core options see MongoCacheStore
+    [+:use_index+ - *true* | false]
+        Default: true
+
+        This should only be set to *false* if all fetch and/or read 
+        operations are passed the *:expires_in* option.  If so, this 
+        will eliminate the need for the key index collection and only 
+        one write and one read operation is necessary. 
+
+
+== Capped
+ 
+*Experimental*
+
+Capped backend for MongoCacheStore
+
+=== Description
+*Experimental* do not use... yet.
+ 
+This should only be used if limiting the size of the cache 
+is of great concern.  Entries are flushed from the cache on 
+a FIFO basis, regardless of the entries expiration time.  
+Delete operations set an entry to expired, but it will not 
+be flushed until it is automatically removed by MongoDB.
+  
+=== Options
+
+TODO
+ 

data/lib/active_support/cache/mongo_cache_store.rb

@@ -8,6 +8,36 @@ module ActiveSupport
 
     class MongoCacheStore < Store
 
+      # Initialize the cache
+      #  
+      # === Attributes  
+      #  
+      # [+backend+ - Symbol representing the backend the cache should use] 
+      #     :TTL | :Standard | :MultiTTL      
+      #
+      # [+options+ - Options for ActiveSupport::Cache and the backend] 
+      #     Core options are listed here.  See each backend for a list of additional optons. 
+      #     [+:db+ - A Mongo::DB instance.]
+      #     [+:db_name+ - Name of database to create if no 'db' is given.] 
+      #     [+:connection+ - A Mongo::Connection instance. Only used if no 'db' is given.] 
+      #     [+:serialize+ - *:always* | :on_fail | :never]
+      #         [+:always+ - (default) - Serialize all entries]
+      #             *NOTE* Without serialization class structures and instances that cannot 
+      #             be converted to a native MongoDB type will not be stored.  Also, 
+      #             without serialization MongoDB converts all symbols to strings.  
+      #             Therefore a hash with symbols as keys will have strings as keys when read. 
+      #
+      #         [+:on_fail+ - Serialize if native format fails]
+      #             Try to save the entry in a native MongoDB format.  If that fails, 
+      #             then serialize the entry. 
+      #         [+:never+ - Never serialize]
+      #             Only save the entry if it can be saved natively by MongoDB.
+      #
+      # === Examples
+      #     @store = ActiveSupport::Cache::MongoCacheStore.new(:TTL, :db => Mongo::DB.new('db_name',Mongo::Connection.new))
+      #
+      #     @store = ActiveSupport::Cache::MongoCacheStore.new(:Standard, :db_name => 'db_name', :connection => Mongo::Connection.new)    
+        
       def initialize (backend=:Standard, options = {})
        
         options = {

data/lib/active_support/cache/mongo_cache_store/backend/capped.rb

@@ -6,10 +6,25 @@ module ActiveSupport
   module Cache
     class MongoCacheStore
       module Backend
-        # MongoCacheStoreBackend for capped collections 
+        # == Capped
+        # 
+        # *Experimental*
+        #
+        # Capped backend for MongoCacheStore
+        #
+        # === Description
+        # *Experimental* do not use... yet.
+        # 
+        # This should only be used if limiting the size of the cache 
+        # is of great concern.  Entries are flushed from the cache on 
+        # a FIFO basis, regardless of the entries expiration time.  
+        # Delete operations set an entry to expired, but it will not 
+        # be flushed until it is automatically removed by MongoDB.
         #  
-        # == Capped Collections
+        # === Options
         #
+        # TODO
+        # 
         module Capped
           include Base
 

data/lib/active_support/cache/mongo_cache_store/backend/multi_ttl.rb

@@ -7,9 +7,43 @@ module ActiveSupport
   module Cache
     class MongoCacheStore
       module Backend
-        # MongoCacheStoreBackend for TTL collections 
+        # == MultiTTL 
+        #
+        # MultiTTL backend for MongoCacheStore
         #  
-        # == Time To Live (TTL) collections 
+        # === Description
+        #
+        # Entries are stored in multiple namespaced TTL collections. 
+        # A namespaced TTL collection is created for each unique expiration time.  
+        # For example all entries with an expiration time of 300 seconds will be 
+        # kept in the same collection while entries with a 900 second expiration 
+        # time will be kept in another.  This requires the use of a *key index* 
+        # collection that keeps track of which TTL collection a entry resides in. 
+        #
+        # ==== Downsides
+        # * Cache set operations require 2 MongoDB write calls.  
+        #   One for the key index, one for the TTL collection. 
+        #   (unless *use_index* is false, see below)
+        # * Cache read operations will require 1 or 2 MongoDB calls 
+        #   depending on whether the 'expires_in' option is set for the read.
+        #
+        # ==== Benefits (future)
+        # * Ability to flush cache based on expire time (TODO)
+        #
+        #
+        # === Additional Options  
+        #  
+        # The following options can be added to a MongoCacheStore constructor
+        #
+        # [+options+ - MultiTTL backend options] 
+        #     To see a list of core options see MongoCacheStore
+        #     [+:use_index+ - *true* | false]
+        #         Default: true
+        #
+        #         This should only be set to *false* if all fetch and/or read 
+        #         operations are passed the *:expires_in* option.  If so, this 
+        #         will eliminate the need for the key index collection and only 
+        #         one write and one read operation is necessary. 
         #
         module MultiTTL
           include Base

data/lib/active_support/cache/mongo_cache_store/backend/standard.rb

@@ -7,9 +7,35 @@ module ActiveSupport
   module Cache
     class MongoCacheStore
       module Backend
-        # MongoCacheStoreBackend for standard collections 
+        # == Standard 
+        #
+        # Standard backend for MongoCacheStore
+        #  
+        # === Description
+        #
+        # Entreis are kept in a namespaced MongoDB collection. In a standard 
+        # collection entries are only flushed from the collection with an 
+        # explicit delete call or if auto_flush is enabled.  If auto_flush is 
+        # enabled the cache will flush all expired entries when auto\_flush\_threshold 
+        # is reached.  The threshold is based on a set number of cache instance writes. 
+        #
+        # === Additional Options  
         #  
-        # == Standard collections 
+        # The following options can be added to a MongoCacheStore constructor
+        #
+        # [+options+ - Standard backend options] 
+        #     To see a list of core options see MongoCacheStore
+        #     [+:auto_flush+ - *true* | false]
+        #         Default: true
+        #
+        #         If auto_flush is enabled the cache will flush all 
+        #         expired entries when auto\_flush\_threshold
+        #         is reached.
+        #     [+:auto_flush_threshold+ - *10_000*] 
+        #         Default: 10_000
+        #
+        #         A number representing the number of writes the when the cache 
+        #         should preform before flushing expired entries.
         #
         module Standard
           include Base

data/lib/active_support/cache/mongo_cache_store/backend/ttl.rb

@@ -6,10 +6,22 @@ module ActiveSupport
   module Cache
     class MongoCacheStore
       module Backend
-        # MongoCacheStoreBackend for OneTTL collections 
-        #  
-        # == OneTTL collections 
+        # == TTL
         #
+        # TTL backend for MongoCacheStore
+        #
+        # === Description
+        #
+        # Entries are kept in a namespaced TTL collection that will 
+        # automatically flush any entries as they pass their expiration 
+        # time. This keeps the size of the cache in check over time. 
+        #
+        # <b>Requires MongoDB 2.0 or higher</b>
+        #
+        # === Additional Options
+        #
+        # No additional options at this time
+        # 
         module TTL
           include Base
 

data/lib/mongo_cache_store/version.rb

@@ -1,4 +1,4 @@
 # -*- encoding : utf-8 -*-
 module MongoCacheStore
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/mongo_cache_store.gemspec

@@ -18,6 +18,6 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
 
   gem.add_dependency 'mongo'
-  gem.add_dependency 'activesupport'
+  gem.add_dependency 'activesupport', '~>3'
   gem.add_development_dependency 'rspec'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mongo_cache_store
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-13 00:00:00.000000000 Z
+date: 2013-01-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mongo
@@ -32,17 +32,17 @@ dependencies:
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -69,7 +69,7 @@ files:
 - .gitignore
 - Gemfile
 - LICENSE.txt
-- README.md
+- README.rdoc
 - Rakefile
 - lib/active_support/cache/mongo_cache_store.rb
 - lib/active_support/cache/mongo_cache_store/backend/base.rb

data/README.md

@@ -1,102 +0,0 @@
-# MongoCacheStore
-
-A MongoDB cache store for ActiveSupport 3
-
-## Description
-
-MongoCacheStore uses pluggable backends to expose MongoDB as a cache store to ActiveSupport applications.  Each backend allows the application to customize how the cache operates.  Support is available for standard, capped and TTL collections.
-
-**WARNING** This gem is in the early stages of development and should be treated as such.  Checking the version of the gem will help with what could be many changes to the backends, options, etc...
-
-While in beta, the major version will always be 0.  The minor version will be increased for anything that breaks the current API.  The patch version will be increased for all changes within a minor revision that add to or fix the current release without changing how the gem is configured or used. 
-
-
-## Backends
-
-A Backend controls how MongoDB collections are used and manipulated as a cache store.
-
-MongoCacheStore ships with 4 backends, TTL, Capped, Standard and MultiTTL.
-
-Planned: GridFS
-  * For very large entries.   Ex: Generate a large report (PDF, DOC, etc...), keep it around for a limited amount of time and have it automatically flush upon expiration.
-
-
-The major difference between each backend involves how entries are flushed.  The core driver will always respect ActiveSupport's *:expires_in* parameter for hits and misses whether the entry has actually been flushed from the backend or not. 
-
-#### Core Options
-From ActiveSupport
-* :namespace
-* :expires_in
-
-For MongoCacheStore
-* :db - A Mongo::DB instance
-* :db_name - Name of database to be created.  Only used if *db* is not set
-* :connection - A Mongo::Connection. Only used if *db* is not set. Defaults to Mongo::Connection.new()
-* serialize: (*:always*, :on\_fail, :never)
-  * :always (default) - Serialize all entries
-  * :on\_fail - Try to save the entry in a native MongoDB format.  If that fails, then serialize the entry. 
-  * :never - only save the entry if it can be saved natively by MongoDB.
-  * *NOTE:* Without serialization class structures and instances that cannot be converted to a native MongoDB type will not be stored.  Also, without serialization MongoDB converts all symbols to strings.  Therefore a hash with symbols as keys will have strings as keys when read.
-
-
-### TTL
-Entries are kept in a namespaced TTL collection that will automatically flush any entries as they pass their expiration time.  This keeps the size of the cache in check over time. 
-  
-* *Requires MongoDB 2.0 or higher*
-
-#### Options
-No Extra options
-
-### Standard
-Entreis are kept in a namespaced MongoDB collection. In a standard collection entries are only flushed from the collection with an explicit delete call or if auto_flush is enabled.  If auto_flush is enabled the cache will flush all expired entries when auto\_flush\_threshold is reached.  The threshold is based on a set number of cache instance writes. 
-
-#### Options
-* auto_flush: (*true*|false)
-* auto\_flush\_threshold: *10_000*
- 
-
-### Capped (TODO)
-This should only be used if limiting the size of the cache is the greatest concern.  Entries are flushed from the cache on a FIFO basis, regardless of the entries expiration time.  Delete operations set an entry to expired, but it will not be flushed until it is automatically removed by MongoDB.
-
-
-### MultiTTL
-Entries are stored in multiple namespaced TTL collections. A namespaced TTL collection is created for each unique expiration time.  For example all entries with an expiration time of 300 seconds will be kept in the same collection while entries with a 900 second expiration time will be kept in another.  This requires the use of a *key index* collection that keeps track of which TTL collection a entry resides in. 
-
-#### Downsides
-  * Cache set operations require 2 MongoDB write calls.  One for the key index, one for the TTL collection. (unless *use_index* is false, see below)
-  * Cache read operations will require 1 or 2 MongoDB calls depending on whether the 'expires_in' option is set for the read.
-
-#### Benefits
-  * Ability to flush cache based on expire time (TODO)
-
-#### Options
-use\_index: (*true*, false)
-  * This should only be set to *false* if all fetch and/or read operations are passed the *:expires_in* option.  If so, this will eliminate the need for the key index collection and only one write and one read operation is necessary. 
-
-
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-    gem 'mongo_cache_store'
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install mongo_cache_store
-
-## Usage
-
-
-
-## Contributing
-
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request