https://github.com/illyasviel/sapphire
A clojure declarative cache library inspired by Spring Cache and JCache.
https://github.com/illyasviel/sapphire
cache clojure jcache
Last synced: about 1 year ago
JSON representation
A clojure declarative cache library inspired by Spring Cache and JCache.
- Host: GitHub
- URL: https://github.com/illyasviel/sapphire
- Owner: illyasviel
- License: apache-2.0
- Created: 2018-10-12T01:09:36.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2019-09-07T02:31:01.000Z (over 6 years ago)
- Last Synced: 2025-04-19T00:34:56.413Z (about 1 year ago)
- Topics: cache, clojure, jcache
- Language: Clojure
- Homepage:
- Size: 51.8 KB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# sapphire
[](https://travis-ci.org/illyasviel/sapphire)
[](https://coveralls.io/github/illyasviel/sapphire?branch=master)
[](https://clojars.org/sapphire)
[](https://versions.deps.co/illyasviel/sapphire)
[](https://versions.deps.co/illyasviel/sapphire)
[](http://www.apache.org/licenses/LICENSE-2.0.html)
A clojure declarative cache library inspired by Spring Cache and JCache.
## Feature
- [JCache](https://jcp.org/en/jsr/detail?id=107) (JSR-107)
- [EhCache 3](http://www.ehcache.org/)
- [Caffeine](https://github.com/ben-manes/caffeine)
- Redis [(Redisson)](https://github.com/redisson/redisson)
- and more...
## Usage
- Adding the following to your `:dependencies`
```clojure
[sapphire "0.1.0-beta4"]
```
- Currently we only support JCache, so you need to choose a provider
and add it to your `:dependencies`
```clojure
[org.ehcache/ehcache "3.7.0"]
```
- Init cache
```clojure
(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`)
```clojure
(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`)
```clojure
(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`)
```clojure
(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`)
```clojure
(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`)
```clojure
(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.
```clojure
(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.