jruby-ehcache 0.5.0 → 1.0.0

data/README.txt

@@ -1,14 +1,14 @@
-= Ehcache for JRuby
+= jruby-ehcache - Ehcache for JRuby
 
 http://github.com/dylanz/ehcache
 
 == DESCRIPTION:
 
-Ehcache is a simplified JRuby interface to Java's (JSR-107 compliant) Ehcache.
-Simplified meaning that it should work out-of-the-box, but a lot of native
-methods haven't been interfaced yet, as they weren't needed.  Configuration
-occurs in config/ehcache.yml, and should support all the configuration
-options available.
+jruby-ehcache is a JRuby interface to Java's (JSR-107 compliant) Ehcache.
+It provides 100% full coverage of the native Ehcache API and also provides
+some Rubyesque enhancements to make it idiomatic to Ruby developers.
+Configuration is done with the traditional ehcache.xml file that Java
+developers use.
 
 Some biased and non-biased Ehcache VS Memcache articles:
 http://gregluck.com/blog/archives/2007/05/comparing_memca.html
@@ -30,33 +30,35 @@ http://dylanz.lighthouseapp.com/projects/14518-ehcache-jruby/overview
 
 
 == BASIC USAGE:
-
+require 'ehcache'
 manager = CacheManager.new
 cache = manager.cache
 cache.put("key", "value", {:ttl => 120})
-cache.get("key")
+cache.get("key")  # => returns the Ehcache Element object
+cache["key"]      # => returns "value", the value of the Element
 manager.shutdown
 
 
 == RAILS:
 
-Rails 2 and Rails 3 integration are provided by the separate ehcache-rails2
-and ehcache-rails3 gems.  To install, choose the correct version for your
-Rails application and use JRuby's gem command to install, e.g.:
+Rails 2 and Rails 3 integration are provided by the separate
+jruby-ehcache-rails2 and jruby-ehcache-rails3 gems.  To install, choose the
+correct version for your Rails application and use JRuby's gem command to
+install, e.g.:
 
-$ jgem install ehcache-rails3
+$ jgem install jruby-ehcache-rails3
 OR
-$ jruby -S gem install ehcache-rails3
+$ jruby -S gem install jruby-ehcache-rails3
 
 
 == REQUIREMENTS:
 
-Tested with JRuby 1.5.0.
+Tested with JRuby 1.5.3.
 
 
 == INSTALL:
 
-$ sudo jruby -S gem install ehcache
+$ sudo jruby -S gem install jruby-ehcache
 
 
 == LICENSE:

data/Rakefile

@@ -1,3 +1,15 @@
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+task :default => [ :test ]
+
+desc "Executes the test suite"
+Rake::TestTask.new do |t|
+  t.name = :test
+  t.libs << 'lib' << 'ext' << 'test'
+  t.pattern = "test/test_*.rb"
+end
+
 begin
   require 'jeweler'
 rescue LoadError
@@ -18,29 +30,31 @@ Jeweler::Tasks.new do |gemspec|
   gemspec.description = "JRuby interface to the popular Java caching library Ehcache"
   gemspec.files.exclude '.gitignore'
 
-  # These files go in the ehcache-rails2 and ehcache-rails3 gems
+  # These files go in the jruby-ehcache-rails2 and jruby-ehcache-rails3 gems
   gemspec.files.exclude 'lib/ehcache_store.rb'
   gemspec.files.exclude 'lib/active_support/**/*'
+  gemspec.files.exclude 'lib/ehcache/rails'
+  gemspec.add_dependency 'activesupport'
 end
 
 Jeweler::Tasks.new do |gemspec|
   defaults(gemspec)
-  gemspec.name = 'ehcache-rails3'
+  gemspec.name = 'jruby-ehcache-rails3'
   gemspec.summary = 'Rails 3 cache store provider using Ehcache'
   gemspec.description = 'Rails 3 cache store provider using Ehcache'
-  gemspec.files = 'lib/active_support/**/*'
+  gemspec.files = FileList['lib/active_support/**/*', 'lib/ehcache/rails/**/*']
   gemspec.test_files = []
-  gemspec.add_dependency 'jruby-ehcache', ">=0.5.0"
+  gemspec.add_dependency 'jruby-ehcache', ">=1.0.0"
 end
 
 Jeweler::Tasks.new do |gemspec|
   defaults(gemspec)
-  gemspec.name = 'ehcache-rails2'
+  gemspec.name = 'jruby-ehcache-rails2'
   gemspec.summary = 'Rails 2 cache store provider using Ehcache'
   gemspec.description = 'Rails 2 cache store provider using Ehcache'
-  gemspec.files = 'lib/ehcache_store.rb'
+  gemspec.files = FileList['lib/active_support/**/*', 'lib/ehcache/rails/**/*']
   gemspec.test_files = []
-  gemspec.add_dependency 'jruby-ehcache', ">=0.5.0"
+  gemspec.add_dependency 'jruby-ehcache', ">=1.0.0"
 end
 
 Jeweler::GemcutterTasks.new

data/VERSION

@@ -1 +1 @@
-0.5.0
+1.0.0

data/config/ehcache.yml

@@ -1,15 +1,15 @@
-disk:
+disk_store:
   path: java.io.tmpdir
 
-peer_provider:
-  class: net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory
+peer_providers:
+- class: net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory
   properties: peerDiscovery=automatic,multicastGroupAddress=230.0.0.1,multicastGroupPort=4446,timeToLive=1
   property_separator: "\,"
 
-peer_listener:
-  class: net.sf.ehcache.distribution.RMICacheManagerPeerListenerFactory
+peer_listeners:
+- class: net.sf.ehcache.distribution.RMICacheManagerPeerListenerFactory
 
-default:
+default_cache:
   name: cache
   max_elements_in_memory:  10000
   time_to_live_seconds:  0

data/config/ehcache_manual_rmi.yml

@@ -1,16 +1,16 @@
-disk:
+disk_store:
   path: java.io.tmpdir
 
-peer_provider:
-  class: net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory
+peer_providers:
+- class: net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory
   properties: peerDiscovery=manual,rmiUrls=//that_hostname:40001/cache
   property_separator: "\,"
 
-peer_listener:
-  class: net.sf.ehcache.distribution.RMICacheManagerPeerListenerFactory
+peer_listeners:
+- class: net.sf.ehcache.distribution.RMICacheManagerPeerListenerFactory
   properties: hostName=this_hostname,port=40000
 
-default:
+default_cache:
   name: cache
   max_elements_in_memory:  10000
   time_to_live_seconds:  0

data/examples/ehcache.xml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="../../main/config/ehcache.xsd">
+
+    <!-- Disable for test ehcache.xml. Should go to the same place. -->
+    <diskStore path="java.io.tmpdir"/>
+
+    <cacheManagerPeerProviderFactory class="net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory"
+                                     properties="peerDiscovery=automatic, multicastGroupAddress=230.0.0.1, multicastGroupPort=4446, timeToLive=0"/>
+
+
+    <cacheManagerPeerListenerFactory class="net.sf.ehcache.distribution.RMICacheManagerPeerListenerFactory"
+                                     properties="hostName=, port=, socketTimeoutMillis="/>
+
+
+    <defaultCache
+            name="default"
+            maxElementsInMemory="10"
+            eternal="false"
+            timeToIdleSeconds="5"
+            timeToLiveSeconds="10"
+            overflowToDisk="true"
+            />
+
+
+    <!-- Sample cache named sampleCache1 -->
+    <cache name="sampleCache1"
+           maxElementsInMemory="10000"
+           maxElementsOnDisk="1000"
+           eternal="false"
+           timeToIdleSeconds="360"
+           timeToLiveSeconds="1000"
+           overflowToDisk="true">
+    </cache>
+
+    <!-- Sample cache named sampleCache2. Is eternal. Is diskPersistent but does not overflow to disk -->
+    <cache name="sampleCache2"
+           maxElementsInMemory="1000"
+           eternal="true"
+           overflowToDisk="false"
+           diskPersistent="true"
+            />
+</ehcache>

data/examples/jruby-ehcache.rb

@@ -0,0 +1,13 @@
+require 'ehcache'
+
+manager = Ehcache::CacheManager.new
+cache = manager.cache
+
+cache.put("answer", "42", {:ttl => 120})
+answer = cache.get("answer")
+puts "Answer: #{answer}"
+
+question = cache.get("question") || 'unknown'
+puts "Question: #{question}"
+
+manager.shutdown

data/lib/ehcache.rb

@@ -1,5 +1,7 @@
-$:.unshift(File.dirname(__FILE__)) unless
-  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+unless $:.include?(File.dirname(__FILE__)) ||
+       $:.include?(File.expand_path(File.dirname(__FILE__)))
+  $:.unshift(File.dirname(__FILE__)) 
+end
 
 require 'java'
 
@@ -12,11 +14,9 @@ module Ehcache
   class EhcacheError < RuntimeError; end
 end
 
+require 'ehcache/extensions'
 require 'ehcache/java'
 require 'ehcache/config'
 require 'ehcache/cache'
 require 'ehcache/cache_manager'
 require 'ehcache/element'
-require 'ehcache/extensions'
-require 'ehcache/version'
-require 'ehcache/status'

data/lib/ehcache/cache.rb

@@ -1,127 +1,58 @@
-module Ehcache
-  class Cache
-    PRIMARY = "cache"
+# Enhance net.sf.ehcache.Cache with a more Rubyesque API.
+class Java::NetSfEhcache::Cache
+  include Enumerable
 
-    # pull cache from given manager by name
-    def initialize(manager, cache_name)
-      @proxy = manager.get_cache(cache_name)
-    end
-
-    # put a new element into the cache
-    def put(key, value, options = {})
-      if key.nil? || key.empty?
-        raise EhcacheError, "Element cannot be blank"
-      end
-      element = Ehcache::Element.new(key, value, options)
-      @proxy.put(element.proxy)
-    rescue NativeException => e
-      raise EhcacheError, e.cause
-    end
-    alias_method :set, :put
-    alias_method :add, :put
-
-    # another alias for put
-    def []=(key, value)
-      put(key, value)
-    end
-
-    # get an element value from cache by key
-    def get(key)
-      element = @proxy.get(key)
-      element ? element.get_value : nil
-    rescue NativeException => e
-      raise EhcacheError, e.cause
-    end
-    alias_method :[], :get
-
-    # get an element from cache by key
-    def element(key)
-      element = @proxy.get(key)
-      return nil unless element
-      Ehcache::Element.new(element.get_key, element.get_value,
-        {:ttl => element.get_time_to_live })
-    rescue NativeException => e
-      raise EhcacheError, e.cause
-    end
-
-    # remove an element from the cache by key
-    def remove(key)
-      @proxy.remove(key)
-    rescue NativeException => e
-      raise EhcacheError, e.cause
-    end
-    alias_method :delete, :remove
-
-    # remove all elements from the cache
-    def remove_all
-      @proxy.remove_all
-    rescue NativeException => e
-      raise EhcacheError, e.cause
-    end
-    alias_method :clear, :remove_all
-
-    def keys
-      @proxy.get_keys
-    end
-
-    def exist?(key)
-      @proxy.is_key_in_cache(key)
-    end
-
-    # returns the current status of the cache
-    def status
-      @proxy.get_status
-    end
-
-    def alive?
-      @proxy.get_status == Status::ALIVE
-    end
-
-    def shutdown?
-      @proxy.get_status == Status::SHUTDOWN
-    end
-
-    def uninitialized?
-      @proxy.get_status == Status::UNINITIALISED
-    end
-
-    # number of elements in the cache
-    def size
-      @proxy.get_size
-    end
-
-    # number of elements in the memory store
-    def memory_size
-      @proxy.get_memory_store_size
-    end
-
-    # number of elements in the cache store
-    def disk_size
-      @proxy.get_disk_store_size
-    end
-
-    # TODO: implement statistics !
-    # return statistics about the cache
-    def statistics
-      @proxy.get_statistics
-    rescue NativeException => e
-      raise EhcacheError, e.cause
+  # Yield each Element stored in this cache to the given block.  This method
+  # uses Cache#getKeys as its basis, and therefore it is possible that some
+  # of the yielded elements have expired.
+  def each
+    for key in self.getKeys
+      yield self.get(key)
     end
+  end
+  # Gets an element value from the cache.  Unlike the #get method, this method
+  # returns the element value, not the Element object.
+  def [](key)
+    element = self.get(key)
+    element ? element.value : nil
+  end
 
-    def max_elements
-      @proxy.get_max_elements_in_memory
-    end
+  alias ehcache_put put
 
-    def eternal?
-      @proxy.is_eternal
-    end
-    
-    def ttl
-      @proxy.get_time_to_live_seconds
+  # Wrap the Cache#put method to allow for extra options to be passed to the
+  # created Element.
+  def put(*args)
+    options = args.extract_options!
+    if args.size == 1 && args.first.kind_of?(Ehcache::Element)
+      element = args.first
+    elsif args.size == 2
+      element = Ehcache::Element.create(args[0], args[1], options)
+    else
+      raise ArgumentError, "Must be Element object or key and value arguments"
     end
+    ehcache_put(element)
+  end
 
-    def tti
-      @proxy.get_time_to_idle_seconds
-    end
+  alias []= put
+
+  alias include? isKeyInCache
+  alias member? isKeyInCache
+
+  # Atomic compare and swap for cache elements.  Invokes the given block with
+  # the current value of the element and attempts to replace it with the
+  # value returned from the block, repeating until replace returns true.
+  # Note that the provided block works only with element values, not Element
+  # objects: the result of element.getValue is passed to the block parameter,
+  # and the block is expected to return a value based on it.
+  # If there is no element with the given key, returns immediately without
+  # retrying.
+  def compare_and_swap(key, &block)
+    begin
+      old_element = self.get(key)
+      return nil unless old_element
+      new_element = Ehcache::Element.new(key, yield(old_element.value))
+    end until replace(old_element, new_element)
   end
+
+  alias update compare_and_swap
 end

data/lib/ehcache/cache_manager.rb

@@ -1,65 +1,69 @@
-module Ehcache
-  class CacheManager
-    def initialize(options={})
-      # TODO document this
-      unless options[:security]
-        import java.lang.System unless defined?(System)
-        import java.rmi.RMISecurityManager unless defined?(RMISecurityManager)
-        RMISecurityManager.new if System.getSecurityManager == nil
-      end
-      @manager = Ehcache::Java::CacheManager.new(Ehcache::Config.generate(options))
-    end
-
-    # return cache by name
-    def cache(cache_name=nil)
-      Ehcache::Cache.new(@manager, cache_name || Ehcache::Cache::PRIMARY)
-    end
-
-    # return all cache names
-    def caches
-      @manager.get_cache_names
-    end
+# Enhance net.sf.ehcache.CacheManager with a more Rubyesque API.
+class Java::NetSfEhcache::CacheManager
+  include Enumerable
 
-    # adds cache based on default configuration
-    def add_cache(cache_name)
-      @manager.add_cache(cache_name)
-    end
+  class << self
+    alias_method :ehcache_create, :create
 
-    # remove cache
-    def remove(cache_name)
-      @manager.remove_cache(cache_name)
-    end
-
-    # remove all caches
-    def remove_all
-      @manager.removal_all
+    # Enhanced create that provides for some extra configuration options.
+    # Specifically, String arguments may be used where native Ehcache expects
+    # java.io.File objects, and if the String refers to a YAML file it will be
+    # used as the Configuration source.
+    def create(*args)
+      process_init_args(*args) do |*args|
+        ehcache_create(*args)
+      end
     end
+  end
 
-    # empty all caches
-    def flush_all
-      @manager.clear_all
+  # Enhanced constructor that provides for some extra configuration options.
+  # Specifically, String arguments may be used where native Ehcache expects
+  # java.io.File objects, and if the String refers to a YAML file it will be
+  # used as the Configuration source.
+  def initialize(*args)
+    process_init_args(*args) do |*args|
+      super(*args)
     end
+  end
 
-    def enable_shutdown_hook
-      @manager.add_shutdown_hook_if_required
+  # Iterate through each cache managed by this CacheManager.
+  def each
+    for name in self.cache_names
+      yield self.get_ehcache(name)
     end
+  end
 
-    def disable_shutdown_hook
-      @manager.disable_shutdown_hook
-    end
+  alias [] get_ehcache
 
-    def shutdown
-      @manager.shutdown
-    end
+  def cache(cache_name = '__default_jruby_cache')
+    self.add_cache_if_absent(cache_name)
+    self.get_ehcache(cache_name)
+  end
 
-    def status
-      @manager.get_status.to_s
-    end
+  # true if cache by given name is being managed, false otherwise
+  def include?(cache_name)
+    self.cache_exists(cache_name)
+  end
+  alias_method :exists?, :include?
+end
 
-    # true if cache by given name is being managed, false otherwise
-    def include?(cache_name)
-      @manager.cache_exists(cache_name)
+# Helper method for processing initialization arguments passed to
+# CacheManager.create and CacheManager#initialize.
+def process_init_args(*args)
+  args.compact!
+  if args.empty?
+    # First, look relative to the file that is creating the CacheManager.
+    # The expression caller[2] finds the entry in the call stack where
+    # CacheManager.new or CacheManager.create was called.
+    creator = /^(.+?):\d/.match(caller[2])[1]
+    if ehcache_config = Java::NetSfEhcacheConfig::Configuration.find(File.dirname(creator))
+      yield(ehcache_config)
+    else
+      yield
     end
-    alias_method :exists?, :include?
+  elsif args.size == 1 && args.first.is_a?(String)
+    yield(Ehcache::Config::Configuration.create(args.first))
+  else
+    yield(*args)
   end
 end