README.md

Redis Cache module for Play framework

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.

About the Project

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.

Features

• 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

Provided APIs

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 CacheApis 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.

Documentation and Getting Started

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:

1. Add this library into your project and expose APIs
2. See the configuration options
3. Browse examples of use

If you come from older version, you might check the Migration Guide

Samples

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.

1. Getting Started is a very basic example showing the minimal configuration required to use the redis cache

2. Named Caches is the advanced example with custom recovery policy and multiple named caches.

3. 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.

How to add the module into the project

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"

Compatibility matrix

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

Contribution

If you encounter any issue, have a feature request, or just like this library, please feel free to report it or contact me.

Changelog

For the list of changes and migration guide please see the Changelog.

Caveat

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.