This version supports Play framework 2.8.x with JDK 8 and both Scala 2.12 and Scala 2.13.
For previous versions see older releases.
Play framework 2 is delivered with SyncCacheApi and AsyncCacheApi. This module provides implementation of a cache over Redis server, i.e., key/value storage.
Besides the compatibility with all Play's cache APIs,
it introduces more evolved API providing lots of handful
operations. Besides the basic methods such as get
, set
and remove
, it provides more convenient methods such as
expire
, exists
, invalidate
and much more.
The implementation builds on the top of Akka actor system,
it is completely non-blocking and asynchronous under
the hood, though it also provides blocking APIs to ease
the use. Furthermore, the library supports several configuration
providers to let you easily use play-redis
on localhost, Heroku,
as well as on your premise.
- synchronous and asynchronous APIs
- implements standard APIs defined by Play's
cacheApi
project - support of named caches
- works with Guice as well as compile-time DI
- getOrElse and getOrFuture operations easing the use
- wildcards in remove operation
- support of collections: sets, lists, and maps
- increment and decrement operations
- eager and lazy invocation policies waiting or not waiting for the result
- several recovery policies and possibility of further customization
- support of several configuration sources
- static in the configuration file
- from the connection string optionally in the environmental variable
- custom implementation of the configuration provider
- support of standalone, cluster, aws-cluster, and sentinel modes
- build on the top of Akka actors and serializers, agnostic to the serialization mechanism
- for simplicity, it uses deprecated Java serialization by default
- it is recommended to use Kryo library or any other mechanism
This library delivers a single module with following implementations of the API. While the core of the framework is fully non-blocking, most of the provided facades are only blocking wrappers.
Trait | Language | Blocking | Features | |
---|---|---|---|---|
1. | play.api.cache.redis.CacheApi |
Scala | blocking | advanced |
2. | play.api.cache.redis.CacheAsyncApi |
Scala | non-blocking | advanced |
3. | play.cache.redis.AsyncCacheApi |
Java | non-blocking | advanced |
4. | play.api.cache.SyncCacheApi |
Scala | blocking | basic |
5. | play.api.cache.AsyncCacheApi |
Scala | non-blocking | basic |
6. | play.cache.SyncCacheApi |
Java | blocking | basic |
7. | play.cache.AsyncCacheApi |
Java | non-blocking | basic |
First, the CacheAsyncApi
provides extended API to work with Redis and enables non-blocking
connection providing results through scala.concurrent.Future
.
Second, the CacheApi
is a thin blocking wrapper around the asynchronous implementation.
Third, there are other implementations supporting contemporary versions of the CacheApi
s
bundled within Play framework. Finally, play-redis
also supports Java version of the API,
though it is primarily designed for and more efficient with Scala.
The full documentation
is in the doc
directory. The documentation for a particular version
is under the particular tag in the Git history
or you can use shortcuts in the table below.
To use this module:
- Add this library into your project and expose APIs
- See the configuration options
- Browse examples of use
If you come from older version, you might check the Migration Guide
To ease the initial learning, there are
several sample projects
intended to demonstrate the most common configurations. Feel free
to study, copy or fork them to better understand the play-redis
use.
-
Getting Started is a very basic example showing the minimal configuration required to use the redis cache
-
Named Caches is the advanced example with custom recovery policy and multiple named caches.
-
EhCache and Redis shows a combination of both caching provides used at once. While the EhCache is bound to unqualified APIs, the Redis cache uses named APIs.
To your SBT build.sbt
add the following lines:
// enable Play cache API (based on your Play version)
libraryDependencies += play.sbt.PlayImport.cacheApi
// include play-redis library
libraryDependencies += "com.github.karelcemus" %% "play-redis" % "2.6.1"
play framework | play-redis | documentation |
---|---|---|
2.8.x | 2.6.1 | see here |
2.7.x | 2.5.1 | see here |
2.6.x | 2.3.0 | see here (Migration Guide) |
2.5.x | 1.4.2 | see here |
2.4.x | 1.0.0 | see here |
2.3.x | 0.2.1 | see here |
If you encounter any issue, have a feature request, or just like this library, please feel free to report it or contact me.
For the list of changes and migration guide please see the Changelog.
The library does not enable the redis module by default. It is to avoid conflict with Play's default EhCache and let the user define when use Redis. This allows you to use EhCache in your dev environment and Redis in production. You can also combine the modules using named caches.