/play-redis

Play framework 2 cache plugin as an adapter to redis-server

Primary LanguageScalaMozilla Public License 2.0MPL-2.0

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.

Travis CI: Status Coverage Status Maven Central

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

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.0"

Compatibility matrix

play framework play-redis documentation
2.8.x 2.6.0 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.