Skip to content

Latest commit

 

History

History
121 lines (73 loc) · 4.44 KB

README.md

File metadata and controls

121 lines (73 loc) · 4.44 KB
Raw

Ehcache support for cache-dot-clj

Cache-dot-clj can be used with the java Ehcache package to provide distributed caching and persistence.

A PDF user guide for Ehcache is available here.

Ehcache is flexible and powerful but comes with a large API and may require XML configuration. The cache-dot-clj.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 cache-dot-clj.cache)
  (:require [cache-dot-clj.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 cache-dot-clj pull in the following dependency using Leiningen, Cake or Maven:

 [uk.org.alienscience/ehcache-dot-clj "0.0.3"]

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.5.11"]

Or if logging is not required:

 [org.sljf4j/slf4j-nop "1.5.11"]

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, cache-dot-clj 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 cache-dot-clj 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 cache-dot-clj.cache using the default configuration or the given cache configuration. The config can be a object of class net.sf.ehcache.config.CacheConfiguration 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 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.