/ehcache/README.md
Markdown | 121 lines | 73 code | 48 blank | 0 comment | 0 complexity | dc42ae3045cf66c393144eff9152684a MD5 | raw file
- # Ehcache support for clj-cache
- This plugin allows clj-cache to be used with the java [Ehcache](http://ehcache.org/) library to provide distributed caching and persistence.
- A PDF user guide for Ehcache is available [here](http://ehcache.org/documentation/EhcacheUserGuide-1.7.1.pdf).
- Ehcache is flexible and powerful but comes with a large API and may require XML configuration. The `clj-cache.ehcache` namespace does its best to isolate casual users from the complexity without limiting access to the underlying java objects and features. However, feedback and feature requests are very welcome.
- ## Example using a default Ehcache configuration
- (ns an-example
- (:use clj-cache.cache)
- (:require [clj-cache.ehcache :as ehcache]))
- (defn-cached get-user-from-db
- (ehcache/strategy)
- [username]
- ;; Slow database read goes here
- )
- ## Example using persistence
- (defn-cached get-user-from-db
- (ehcache/strategy {:max-elements-in-memory 1000
- :eternal true
- :overflow-to-disk true
- :disk-persistent true
- :clear-on-flush true})
- [username]
- ;; Slow database read goes here
- )
- ## Dependencies
- To use Ehcache and clj-cache pull in the following dependency using Leiningen, Cake or Maven:
- [clj-cache-ehcache "0.0.4"]
- Ehcache uses slf4j to do logging and a slf4j plugin must be included as a dependency. To log to stderr you can use:
- [org.sljf4j/slf4j-simple "1.6.1"]
- Or if logging is not required:
- [org.sljf4j/slf4j-nop "1.6.1"]
- ## Limitations
- This package assumes all keys and values in the cache are `java.io.Serializable`. This covers most clojure datastructures but means that different versions of clojure (e.g 1.1 and 1.2) shouldn't share the same distributed cache.
- Internally, clj-cache uses features found in clojure to limit the number of calls to slow functions on a cache miss. Ehcache can also do this using locking. Locking in Ehcache is relatively new, requires an additional package and is not well documented. Because of this clj-cache does not yet support locking with Ehcache. However, if there is interest, locking can be added at a later date.
- # API
- ## strategy [] [config] [manager config]
- Returns a strategy for use with clj-cache.cache using the
- default configuration or the given cache configuration.
- The config can be a object of class [net.sf.ehcache.config.CacheConfiguration](http://ehcache.org/apidocs/net/sf/ehcache/config/CacheConfiguration.html) or a clojure map containing keys that correspond to the setters
- of the Cache configuration. The keys are converted to camelCase internally
- , so for example:
- {:max-elements-in-memory 100} calls setMaxElementsInMemory(100)
- A CacheManager can also be passed in as the first argument, without this the singleton CacheManager is used (which should be fine for most uses).
- ## new-manager [] [config]
- Creates a new cache manager. The config can be a filename string, URL object or an InputStream containing an XML configuration. To set the configuration without using an external XML file, a clojure [prxml](http://richhickey.github.com/clojure-contrib/prxml-api.html#clojure.contrib.prxml/prxml) style datastructure can be used.
- ### example
- (new-manager
- [:ehcache
- [:disk-store
- {:path "java.io.tmpdir/mycaches"}]
- [:default-cache
- {:max-elements-in-memory 100
- :eternal false
- :overflow-to-disk true
- :disk-persistent false
- :memory-store-eviction-policy "LRU"}]])
- ## Access to Ehcache objects and features
- - add [cache k v]
- Adds an item to the given cache and returns the value added.
- - lookup [cache k]
- Looks up an item in the given cache. Returns a vector [element-exists? value].
- - invalidate [cache k]
- Invalidates the cache entry with the given key.
- - create-config []
- Creates a CacheConfiguration object.
- The functions below can also be called with a CacheManager as the first argument. If a a CacheManager is not passed in then the singleton CacheManager is used.
- - create-cache [cache-name config]
- Returns an ehcache Cache object with the given name and config.
- - cache-seq []
- Returns a sequence containing the names of the currently used caches within a cache manager.
- - remove-cache [cache-name]
- Removes the cache with the given name.
- - shutdown []
- Shuts down a cache manager.