immutant.caching — org.immutant/caching 2.1.10

Create, manage and manipulate Infinispan caches in a data grid

add-listener! clj

(add-listener! cache f type & types)

Attaches a listener fn to cache to be notified on certain events.

Infinispan's cache notifications API is based on Java annotations, which can be awkward in Clojure (and Java, for that matter).

This function provides the ability to be notified of cache events via single-arity callback functions taking an Infinispan Event instance.

Event types are represented as keywords corresponding to the Infinispan annotations:

• :cache-entries-evicted
• :cache-entry-activated
• :cache-entry-created
• :cache-entry-invalidated
• :cache-entry-loaded
• :cache-entry-modified
• :cache-entry-passivated
• :cache-entry-removed
• :cache-entry-visited
• :data-rehashed
• :topology-changed
• :transaction-completed
• :transaction-registered

The callbacks are synchronous, i.e. invoked on the thread acting on the cache. For longer running callbacks, use a queue or some sort of asynchronous channel.

The return value is a sequence of listener objects corresponding to the requested event types, which will be a subset of those returned from the cache's own getListeners method. These may be passed to the cache's removeListener method to turn off notifications.

builder clj

(builder & options)

For advanced use, call this function to obtain a "fluent" ConfigurationBuilder. Set the desired options, and invoke its build method, the result from which can be passed via the :configuration option of the cache function. For example:

(let [config (.. (builder :ttl [30 :minutes])
                clustering l1 (enabled true) build)]
  (cache "L1" :configuration config))

Note that builder takes the same options as cache so you can concisely initialize it with Clojure, and use Java interop to set the more esoteric options

cache clj

(cache name & opts)

Returns a reference to the cache named by name, creating it if necessary.

name is the only required argument. If a cache by that name already exists, it will be returned, and any options passed to this function will be ignored. To force reconfiguration, call stop before calling cache. The return value is a org.infinispan.Cache, an extension of java.util.concurrent.ConcurrentMap.

The following groups of options are supported, each listed with its [default] value. A negative value for any numeric option means "unlimited".

Durability: entries can persist to disk via the :persist option. If set to true, cache entries will persist in the current directory. Override this by setting :persist to a string naming the desired directory.

• :persist - if non-nil, data persists across server restarts in a file store; a string value names the directory [nil]

Eviction: turned off by default, :max-entries may be set to mitigate the risk of memory exhaustion. When :persist is enabled, evicted entries are written to disk, so that the entries in memory are a subset of those in the file store, transparently reloaded upon request. The eviction policy may be one of :none, :lru, :lirs, or :unordered

• :max-entries - the max number of entries allowed in the cache [-1]
• :eviction - how entries are evicted when :max-entries is exceeded [:none]

Expiration: both time-to-live and max idle limits are supported. Values may be a number of milliseconds, a period keyword, or multiplier/keyword pairs, e.g. [1 :hour 20 :minutes]. Both singular and plural versions of :second, :minute, :hour, :day, and :week are valid period keywords.

• :ttl - the max time the entry will live before expiry [-1]
• :idle - the time after which an entry will expire if not accessed [-1]

Replication: the replication mode defaults to :dist-sync when clustered. When not clustered, the value of :mode is ignored, and the cache will be :local. Asynchronous replication may yield a slight performance increase at the risk of potential cache inconsistency.

• :mode - replication mode, one of :local, :repl-sync, :repl-async, :invalidation-sync, :invalidation-async, :dist-sync, :dist-async [:dist-sync or :local]

Transactions: caches can participate in transactions when a TransactionManager is available. The locking scheme may be either :optimistic or :pessimistic

• :transactional? - whether the cache is transactional [false]
• :locking - transactional locking scheme [:optimistic]

Advanced configuration: the options listed above are the most commonly configured, but Infinispan has many more buttons, switches, dials, knobs and levers. Call the builder function to create your own Configuration instance and pass it in via the :configuration option.

• :configuration - a Configuration instance

exists? clj

(exists? name)

Return true if the named cache exists

stop clj

(stop cache-or-name)

Removes a cache, allowing it to be reconfigured by the cache function.

swap-in! clj

(swap-in! cache key f & args)

Atomically swaps the value associated to the key in the cache with the result of applying f, passing the current value as the first param along with any args, returning the new cached value. Function f should have no side effects, as it may be called multiple times. If the key is missing, the result of applying f to nil will be inserted atomically.

with-codec clj

(with-codec cache codec)

Decorates cache with the codec named by codec.

Takes a cache and a keyword denoting a codec, and returns a new cache that applies that codec as entries are written/read to/from the passed cache. This is typically necessary only when non-clojure clients are sharing the cache. It's required if you wish to store nil keys or values. The provided codecs are :edn and :json (the latter requires you to depend on cheshire), and you can also use any other codecs you may have registered.

with-expiration clj

(with-expiration cache & options)

Decorates cache with the given expiration options.

The return value is a cache that will delegate any writes to the passed cache according to these options:

• :ttl - the max time the entry will live before expiry [-1]
• :idle - the time after which an entry will expire if not accessed [-1]

Options may be passed as either keyword arguments or in a map.

Negative values imply "unlimited". Values may be a number of milliseconds, a period keyword, or multiplier/keyword pairs, e.g. [1 :hour 20 :minutes]. Both singular and plural versions of :second, :minute, :hour, :day, and :week are valid period keywords.

Expiration for existing entries in the passed cache will not be affected.