feedtools_ram_cache 1.0

data/CHANGELOG

@@ -0,0 +1 @@
+v1.0. Initial release, tested to work with FeedTools 0.2.29.

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2009 Zergling.Net
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Manifest

@@ -0,0 +1,9 @@
+CHANGELOG
+LICENSE
+Manifest
+README.textile
+Rakefile
+lib/feed_tools_ram_cache.rb
+test/cache_test.rb
+test/fixtures/unit.yml
+test/integration_test.rb

data/README.textile

@@ -0,0 +1,63 @@
+h1. RAM-backed cache for FeedTools
+
+FeedTools is a Ruby gem and Rails plug-in than parses both RSS and Atom feeds
+reliably. The library was intended to be used inside Rails, and comes with the
+entire kitchen sink, including a caching mechanism based on ActiveRecord and a
+database table.
+
+This gem implements a RAM-backed cache, so FeedTools clients can get the
+benefits of caching without taking a dependency on ActiveRecord. The RAM-backed
+cache's contents can be serialized using YAML.
+
+h2. Setup
+
+bc. rubygems install feedtools_ram_cache 
+
+h2. Usage
+
+The gem does not interfere with the FeedTools API. To enable RAM-based caching,
+require the gem and configure FeedTools to use it:
+
+bc. require 'feed_tools_ram_cache'
+FeedTools.configurations[:feed_cache] = 'RamFeedCache' 
+
+h3. Serializing the Cache State
+
+The cache state is a Ruby @Hash@ available via the class attribute @state@. It
+can be stored in a YAML file, or loaded from a file. This can come in handy for
+tests.
+
+bc. # Save the cache state to state.yml
+File.open('state.yml', 'w') { |f| YAML.dump FeedTools::RamFeedCache.state, f }
+# Load the cache state from state.yml
+FeedTools::RamFeedCache.state = YAML.load File.read('state.yml')
+ 
+h3. Clearing the Cache
+
+The RAM-backed cache does not implement a size limitation. However, the cache 
+can be cleared. This prevents it from growing indefinitely, and also provides a
+clean slate for testing.
+
+bc. FeedTools::RamFeedCache.clear
+
+h2. Naming Convention
+
+The naming scheme for this gem is confusing, but it is consistent with the
+naming of the FeedTools gem that it extends.
+
+The gem is named +feedtools_ram_cache+, but the name of the library to be
+required in Ruby is +feed_tools_ram_cache. This is consistent with FeedTools, 
+whose gem name is +feedtools+, providing the library +feed_tools+.
+
+h2. Requirements
+
+The gem depends on the +feedtools+ version used to test the code. If you need
+the RAM-based cache for an older version of +feedtools+, try to run the tests
+(via @rake test@) against your version of +feedtools+. If the tests pass, send
+me a pull request.
+
+h2. Contributions
+
+I wrote the RAM-backed cache to fulfill my very specific needs. I will not be
+adding features, but I will do my best to fix bugs. If you want a feature,
+please don't hesitate to fork the project and send me pull requests.

data/Rakefile

@@ -0,0 +1,28 @@
+# Rakefile that uses echoe to manage feed_tools_ram_cache's gemspec. 
+#
+# Author:: Victor Costan
+# Copyright:: Copyright (C) 2009 Zergling.Net
+# License:: MIT
+
+require 'rubygems'
+require 'echoe'
+
+Echoe.new('feedtools_ram_cache') do |p|
+  p.project = 'zerglings'  # RubyForge project.
+  
+  p.author = 'Victor Costan'
+  p.email = 'victor@zergling.net'
+  p.summary = "RAM-based cache for FeedTools."
+  p.url = 'http://github.com/costan/feed_tools_ram_cache'
+  p.dependencies = ["feed_tools >=0.2.29"]
+  p.development_dependencies = ["echoe >=3.1.1", "flexmock >=0.8.6"]
+  
+  p.need_tar_gz = true
+  p.need_zip = true
+  p.rdoc_pattern = /^(lib|bin|tasks|ext)|^BUILD|^README|^CHANGELOG|^TODO|^LICENSE|^COPYING$/  
+end
+
+if $0 == __FILE__
+  Rake.application = Rake::Application.new
+  Rake.application.run
+end

data/feedtools_ram_cache.gemspec

@@ -0,0 +1,40 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{feedtools_ram_cache}
+  s.version = "1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Victor Costan"]
+  s.date = %q{2009-09-20}
+  s.description = %q{RAM-based cache for FeedTools.}
+  s.email = %q{victor@zergling.net}
+  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "README.textile", "lib/feed_tools_ram_cache.rb"]
+  s.files = ["CHANGELOG", "LICENSE", "Manifest", "README.textile", "Rakefile", "lib/feed_tools_ram_cache.rb", "test/cache_test.rb", "test/fixtures/unit.yml", "test/integration_test.rb", "feedtools_ram_cache.gemspec"]
+  s.homepage = %q{http://github.com/costan/feed_tools_ram_cache}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Feedtools_ram_cache", "--main", "README.textile"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{zerglings}
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{RAM-based cache for FeedTools.}
+  s.test_files = ["test/cache_test.rb", "test/integration_test.rb"]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<feed_tools>, [">= 0.2.29"])
+      s.add_development_dependency(%q<echoe>, [">= 3.1.1"])
+      s.add_development_dependency(%q<flexmock>, [">= 0.8.6"])
+    else
+      s.add_dependency(%q<feed_tools>, [">= 0.2.29"])
+      s.add_dependency(%q<echoe>, [">= 3.1.1"])
+      s.add_dependency(%q<flexmock>, [">= 0.8.6"])
+    end
+  else
+    s.add_dependency(%q<feed_tools>, [">= 0.2.29"])
+    s.add_dependency(%q<echoe>, [">= 3.1.1"])
+    s.add_dependency(%q<flexmock>, [">= 0.8.6"])
+  end
+end

data/lib/feed_tools_ram_cache.rb

@@ -0,0 +1,122 @@
+# RAM-backed cache for FeedTools.
+#
+# Author:: Victor Costan
+# Copyright:: Copyright (C) 2009 Zergling.Net
+# License:: MIT
+
+require 'rubygems'
+require 'feed_tools'
+
+# :nodoc: namespace
+module FeedTools
+
+
+# RAM-backed cache for FeedTools.
+#
+# This is a drop-in replacement for FeedTools::DatabaseFeedCache that does not
+# require a database.
+class RamFeedCache
+  # Creates a new cache item.
+  def initialize(initial_values = {})
+    @fields = initial_values.dup
+  end
+  
+  # The fields in this cache item.
+  attr_reader :fields
+  
+  # The cache state, in a format that can be serialized.
+  def self.state
+    @by_id.values.map { |value| value.fields }
+  end
+  
+  # Loads previously saved state into the cache.
+  def self.state=(new_state)
+    clear
+    new_state.each { |fields| write_item RamFeedCache.new(fields) }
+  end
+  
+  # Removes all the cache items.
+  def self.clear
+    @by_id, @by_href = nil, nil
+    initialize_cache    
+  end
+    
+  # Fields required by FeedTools.
+  #
+  # The FeedTools documentation is outdated. The correct fields can be inferred
+  # from the migration found at:
+  #     http://feedtools.rubyforge.org/svn/trunk/db/migration.rb
+  FIELDS =  [:id, :href, :title, :link, :feed_data, :feed_data_type,
+             :http_headers, :last_retrieved, :time_to_live, :serialized]
+  FIELDS.each do |field_name|
+    define_method(field_name) { @fields[field_name] }
+    define_method(:"#{field_name}=") { |value| @fields[field_name] = value }
+  end
+  
+  # Cache indexes.
+  @by_id, @by_href = nil, nil
+  
+  # Writes an item into the cache
+  def self.write_item(item)
+    # NOTE: FeedTools seems to rely on ActiveRecord's auto-incrementing IDs.
+    item.id = @by_id.length + 1 unless item.id
+
+    @by_id[item.id] = item
+    @by_href[item.href] = item
+  end    
+  
+  # Called by FeedTools to save the cache item.
+  def save
+    self.class.write_item(self)
+    true
+  end
+  
+  # Called by FeedTools to initialize the cache.
+  def self.initialize_cache
+    # NOTE: the FeedTools documentation says this will be called once. In fact,
+    #       the method is called over and over again.
+    @by_id ||= {}
+    @by_href ||= {}
+  end
+
+  # Called by FeedTools to determine if the cache is online.
+  def self.connected?
+    @by_id != nil
+  end
+  
+  # FeedTools documentation doesn't specify this method, but the implementation
+  # calls it.
+  def self.set_up_correctly?
+    connected?
+  end
+  
+  # FeedTools documentation doesn't specify this method, but the implementation
+  # calls it.
+  def self.table_exists?
+    true
+  end
+  
+  # Required by FeedTools.
+  def self.find_by_id(id)
+    @by_id[id]
+  end
+  
+  # Required by FeedTools.
+  def self.find_by_href(url)
+    @by_href[url]
+  end
+
+  # Good idea: override equality comparison so it works for equal cache entries.
+  #            Must also override hash, since we're overriding ==.
+  
+  def ==(other)
+    return false unless other.kind_of?(RamFeedCache)
+    @fields == other.fields
+  end
+  
+  def hash
+    @fields.hash
+  end
+end  # class RamFeedCache
+
+end  # namespace FeedTools

data/test/cache_test.rb

@@ -0,0 +1,113 @@
+# Author:: Victor Costan
+# Copyright:: Copyright (C) 2009 Zergling.Net
+# License:: MIT
+
+require 'feed_tools_ram_cache'
+require 'test/unit'
+
+
+class CacheTest < Test::Unit::TestCase
+  Cache = FeedTools::RamFeedCache
+  
+  def setup
+    Cache.state = []
+    Cache.new(:href => "google").save
+    Cache.new(:href => "yahoo").save
+    Cache.new(:href => "bing", :id => 100).save
+    Cache.new(:href => "ask").save    
+    
+    @golden_fields = Hash[*Cache::FIELDS.map { |f| [f, _value(f)] }.flatten]
+    fixtures_path = File.join File.dirname(__FILE__), 'fixtures' 
+    @golden_state = YAML.load File.read(File.join(fixtures_path, 'unit.yml'))
+  end
+  
+  # The golden value for a field. This is the field's value in golden_state.
+  def _value(field)
+    "Value: #{field} - #{field.to_s.reverse}"
+  end
+  
+  def _check_field_fetch(item)
+    Cache::FIELDS.each do |field|
+      assert_equal _value(field), item.send(field),
+                   "Field fetch check failed for field #{field}"
+    end
+  end
+  
+  def _check_state(item)
+    assert_equal @golden_fields, item.fields, 'Item state check failed'
+  end
+  
+  def test_item_fields
+    item = Cache.new
+    Cache::FIELDS.each { |field| item.send :"#{field}=", _value(field) }
+    _check_field_fetch item
+    _check_state item    
+  end
+  
+  def test_item_state_load
+    item = Cache.new @golden_fields
+    _check_field_fetch item
+    _check_state item
+  end
+  
+  def test_find_by_id
+    assert_equal nil, Cache.find_by_id(0), 'ID 0 should not exist'
+    assert_equal 'google', Cache.find_by_id(1).href
+    assert_equal 'yahoo', Cache.find_by_id(2).href
+    assert_equal 'bing', Cache.find_by_id(100).href
+    assert_equal 'ask', Cache.find_by_id(4).href
+  end
+  
+  def test_find_by_href
+    assert_equal nil, Cache.find_by_href('inktomi'), 'Inktomi should not exist'
+    assert_equal 1, Cache.find_by_href('google').id
+    assert_equal 2, Cache.find_by_href('yahoo').id 
+    assert_equal 100, Cache.find_by_href('bing').id  
+    assert_equal 4, Cache.find_by_href('ask').id
+  end
+  
+  def test_equality
+    assert_equal Cache.find_by_id(1), Cache.find_by_href('google')             
+    assert_not_equal Cache.find_by_id(2), Cache.find_by_href('google')
+    assert_not_equal Cache.find_by_id(2), nil
+    assert_not_equal nil, Cache.find_by_href('google')
+  end
+  
+  def test_hash
+    assert_equal Cache.new(Cache.find_by_id(1).fields).hash,
+                 Cache.find_by_href('google').hash
+    assert_not_equal Cache.find_by_id(2).hash, Cache.find_by_href('google').hash
+  end
+  
+  def test_state_storing
+    #File.open('test/fixtures/unit.yml', 'w') do |f|
+    #  YAML.dump Cache.state, f
+    #end
+    assert_equal @golden_state, Cache.state
+  end
+  
+  def test_clear
+    Cache.clear
+    assert_equal nil, Cache.find_by_id(1), 'Cache not deleted - found ID 1'
+    assert_equal nil, Cache.find_by_href('google'),
+                 'Cache not deleted - found HREF google'  
+  end
+  
+  def test_state_loading
+    Cache.state = [{:id => 1}]
+    
+    assert_equal nil, Cache.find_by_id(2), 'Cache state not reset - found ID 2'
+    assert_equal nil, Cache.find_by_href('google'),
+                 'Cache state not reset - found google'
+  end
+  
+  def test_state_reloading
+    Cache.clear
+    Cache.state = @golden_state
+    
+    test_find_by_id
+    test_find_by_href
+    test_equality
+    test_hash
+  end
+end

data/test/fixtures/unit.yml

@@ -0,0 +1,9 @@
+--- 
+- :href: bing
+  :id: 100
+- :href: google
+  :id: 1
+- :href: yahoo
+  :id: 2
+- :href: ask
+  :id: 4

data/test/integration_test.rb

@@ -0,0 +1,54 @@
+# Author:: Victor Costan
+# Copyright:: Copyright (C) 2009 Zergling.Net
+# License:: MIT
+
+require 'feed_tools_ram_cache'
+require 'test/unit'
+
+require 'benchmark'
+require 'open-uri'
+
+
+class IntegrationTest < Test::Unit::TestCase
+  def setup
+    FeedTools.configurations[:feed_cache] = 'RamFeedCache'
+    FeedTools::RamFeedCache.clear
+  end
+  
+  def test_with_atom
+    uri = 'http://feeds2.feedburner.com/VictorCostan'
+    _test_cache uri
+  end
+  
+  def test_with_rss
+    uri = 'http://events.mit.edu/rss/'
+    _test_cache uri
+  end
+  
+  def _test_cache(uri)
+    feed, cached_feed = nil, nil
+    time = Benchmark.realtime { feed = FeedTools::Feed.open uri }
+    
+    # Make sure the cache's state is YAML-serializable
+    yaml_state = FeedTools::RamFeedCache.state.to_yaml
+    FeedTools::RamFeedCache.state = YAML.load yaml_state
+    
+    cached_time = Benchmark.realtime { cached_feed = FeedTools::Feed.open uri }
+
+    assert !cached_feed.live?, 'cached_feed is live?'
+    assert_operator cached_time, :< , time / 3,
+                    'Cached retrieval should be faster'    
+    
+    assert_equal feed.items.length, cached_feed.items.length,
+                 'Incorrect cached data (item count)'
+    feed.items.each_index do |i|
+      [:guid, :published, :link, :summary, :description].each do |field|
+        assert_equal cached_feed.items[i].send(field),
+                     feed.items[i].send(field),
+                     "Incorrect cached data at index #{i} field #{field}: " +
+                     feed.items[i].inspect + ' vs ' + 
+                     cached_feed.items[i].inspect
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification 
+name: feedtools_ram_cache
+version: !ruby/object:Gem::Version 
+  version: "1.0"
+platform: ruby
+authors: 
+- Victor Costan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-20 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: feed_tools
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.2.29
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: echoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 3.1.1
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: flexmock
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.8.6
+    version: 
+description: RAM-based cache for FeedTools.
+email: victor@zergling.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- CHANGELOG
+- LICENSE
+- README.textile
+- lib/feed_tools_ram_cache.rb
+files: 
+- CHANGELOG
+- LICENSE
+- Manifest
+- README.textile
+- Rakefile
+- lib/feed_tools_ram_cache.rb
+- test/cache_test.rb
+- test/fixtures/unit.yml
+- test/integration_test.rb
+- feedtools_ram_cache.gemspec
+has_rdoc: true
+homepage: http://github.com/costan/feed_tools_ram_cache
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Feedtools_ram_cache
+- --main
+- README.textile
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "1.2"
+  version: 
+requirements: []
+
+rubyforge_project: zerglings
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: RAM-based cache for FeedTools.
+test_files: 
+- test/cache_test.rb
+- test/integration_test.rb