sapphire

A clojure declarative cache library inspired by Spring Cache and JCache.

Feature

• JCache (JSR-107)
  • EhCache 3
  • Caffeine
  • Redis (Redisson)
  • and more...

Usage

• Adding the following to your :dependencies

[sapphire "0.1.0-beta4"]

• Currently we only support JCache, so you need to choose a provider and add it to your :dependencies

[org.ehcache/ehcache "3.7.0"]

• Init cache

(ns sapphire.example
  (:require [sapphire.core :refer :all]
            [sapphire.cache :as cache]))

;; ehcache 3
(cache/sapphire-init!
  :cache-manager (cache/jcache-cache-manager-factory
                   :fully-qualified-class-name "org.ehcache.jsr107.EhcacheCachingProvider"
                   :config-file-path "ehcache3.xml")) ;; <-- Provider also need a configuration file.

• Cache Result (:cache-result)

(defcomponent find-user-by-id
  "The result is cacheable."
  {:cache-result {:cache-name "user"}}
  [id]
  (prn "Get from database.."))
;; => #'user/find-user-by-id
(find-user-by-id 666)
;; "Get from database.."
;; => nil
(find-user-by-id 666)
;; => nil

• Cache Put (:cache-put)

(defcomponent put-user-into-cache
  "Explicit put the data into cache."
  {:cache-put {:cache-name "user", :key cache/first-param}}
  [id user]
  (prn "Put the result into cache.")
  user)
;; => #'user/put-user-into-cache
(put-user-into-cache 777 {:username "777"})
;; "Put the result into cache."
;; => {:username "777"}
(find-user-by-id 777)
;; => {:username "777"}

• Cache Remove By Key (:cache-remove)

(defcomponent remove-user-from-cache
  "Remove data from cache."
  {:cache-remove {:cache-name "user", :key cache/take-all-params}}
  [id]
  (prn "Remove data from cache by id."))
;; => #'user/remove-user-from-cache
(remove-user-from-cache 777)
;; "Remove data from cache by id."
;; => nil
(find-user-by-id 777)
;; "Get from database.."
;; => nil

• Cache Remove All (:cache-remove-all)

(defcomponent remove-all-user-from-cache
  "Remove data from cache."
  {:cache-remove-all {:cache-name "user"}}
  []
  (prn "Remove all data from cache."))
;; => #'user/remove-all-user-from-cache
(remove-all-user-from-cache)
;; "Remove all data from cache."
;; => nil
(find-user-by-id 666)
;; "Get from database.."
;; => nil

• Default cache metadata (:cache-defaults)

(ns sapphire.example
  "You can offer default cache config for all cache components in current namespace."
  {:cache-defaults {:cache-name "user"}}
  (:require [sapphire.core :refer :all]
            [sapphire.cache :as cache]))

• Keep sapphire metadata

By default, sapphire's metadata will not be retained. Unless you specify :keep-sapphire-meta on the current namespace or function.

(ns sapphire.example
  {:keep-sapphire-meta true}
  (:require [sapphire.core :refer :all]
            [sapphire.cache :as cache]))
            
(defcomponent keep-sapphire-metadata
  {:keep-sapphire-meta true}
  []
  (prn "Do something."))

Documents

Macro

Macro	Description
defcomponent	Based on clojure.core/defn and has the same syntax. Put the sapphire metadata into attr-map.

Metadata

Metadata Key	Description
:keep-sapphire-meta	true. By default, sapphire's metadata will not be retained. Unless you specify :keep-sapphire-meta on the current namespace or function
:cache-defaults	{}. Specify the default cache config for current namespace.
	{:cache-name ""}. Default cache name.
	{:key-generator func}. Default key generator.
:cache-result	{}. Cache the result for current function by key.
	{:cache-name ""}. Specify the cache name used to get cache from cache manager.
	{:key func}. Specify the function used to take params that will be passed to key generator.
	{:key-generator func}. Specify the function used to generate key. (key-generator (key args))
	{:sync true}. Synchronize the invocation of the underlying method if several threads are attempting to load a value for the same key. This is effectively a hint and the actual cache provider that you are using may not support it in a synchronized fashion.
:cache-put	{}. Explicitly put the result into cache by key.
	{:cache-name ""}.
	{:key func}.
	{:key-generator func}.
:cache-remove	{}. Explicitly remove data from cache by key.
	{:cache-name ""}.
	{:key func}.
	{:key-generator func}.
:cache-remove-all	{}. Explicitly remove all data from cache.
	{:cache-name ""}.
endAndKeepThisTableWidth	endAndKeepThisTableWidth

Built-in key func

Func	Description
cache/take-all-params	The default key func, take all params as key.
cache/first-param	Take the first param as key.
(cache/take-n-params n)	Take n params as key.