Spring Data Redis Version 1.7.1.RELEASE

, Jennifer Hickey, Christoph Strobl, Thomas Darimont, Mark Paluch Version 1.7.1.RELEASE, 2016-04-06

© 2011-2016 The original authors. http://docs.spring.io/spring-data/redis/docs/1.7.1.RELEASE/reference/html/#tx

Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

Preface

The Spring Data Redis project applies core Spring concepts to the development of solutions using a key-value style data store. We provide a "template" as a high-level abstraction for sending and receiving messages. You will notice similarities to the JDBC support in the Spring Framework.

1. New Features

New and noteworthy in the latest releases.

1.1. New in Spring Data Redis 1.6

• The Lettuce Redis driver switched from wg/lettuce to mp911de/lettuce.

• Support for ZRANGEBYLEX.

• Enhanced range operations for ZSET s including +inf / -inf.

• Performance improvements in RedisCache now releasing connections earlier.

• Generic Jackson2 RedisSerializer making use of Jackson’s polymorphic deserialization.

1.2. New in Spring Data Redis 1.5

• Add support for Redis HyperLogLog commands PFADD, PFCOUNT and PFMERGE.

• Configurable JavaType lookup for Jackson based RedisSerializers.

• PropertySource based configuration for connecting to Redis Sentinel (see: Redis Sentinel Support).

Introduction

This document is the reference guide for Spring Data Redis (SDR) Support. It explains Key Value module concepts and semantics and the syntax for various stores namespaces.

For an introduction to key value stores or Spring, or Spring Data examples, please refer to Getting Started - this documentation refers only to Spring Data Redis Support and assumes the user is familiar with the key value storages and Spring concepts.

2. Why Spring Data Redis?

The Spring Framework is the leading full-stack Java/JEE application framework. It provides a lightweight container and a non-invasive programming model enabled by the use of dependency injection, AOP, and portable service abstractions.

NoSQL storages provide an alternative to classical RDBMS for horizontal scalability and speed. In terms of implementation, Key Value stores represent one of the largest (and oldest) members in the NoSQL space.

The Spring Data Redis (or SDR) framework makes it easy to write Spring applications that use the Redis key value store by eliminating the redundant tasks and boiler plate code required for interacting with the store through Spring’s excellent infrastructure support.

3. Requirements

Spring Data Redis 1.2.x binaries requires JDK level 6.0 and above, and Spring Framework 3.2.8 and above.

In terms of key value stores, Redis 2.6.x or higher is required. Spring Data Redis is currently tested against the latest 2.6 and 2.8 releases.

4. Getting Started

Learning a new framework is not always straight forward. In this section, we (the Spring Data team) tried to provide, what we think is, an easy to follow guide for starting with the Spring Data Redis module. Of course, feel free to create your own learning 'path' as you see fit and, if possible, please report back any improvements to the documentation that can help others.

4.1. First Steps

As explained in Why Spring Data Redis?, Spring Data Redis (SDR) provides integration between Spring framework and the Redis key value store. Thus, it is important to become acquainted with both of these frameworks (storages or environments depending on how you want to name them). Throughout the SDR documentation, each section provides links to resources relevant however, it is best to become familiar with these topics beforehand.

4.1.1. Knowing Spring

Spring Data uses heavily Spring framework’s core functionality, such as the IoC container, resource abstract or AOPinfrastructure. While it is not important to know the Spring APIs, understanding the concepts behind them is. At a minimum, the idea behind IoC should be familiar. That being said, the more knowledge one has about the Spring, the faster she will pick up Spring Data Redis. Besides the very comprehensive (and sometimes disarming) documentation that explains in detail the Spring Framework, there are a lot of articles, blog entries and books on the matter - take a look at the Spring Guides home page for more information. In general, this should be the starting point for developers wanting to try Spring DR.

4.1.2. Knowing NoSQL and Key Value stores

NoSQL stores have taken the storage world by storm. It is a vast domain with a plethora of solutions, terms and patterns (to make things worse even the term itself has multiple meanings). While some of the principles are common, it is crucial that the user is familiar to some degree with the stores supported by SDR. The best way to get acquainted with these solutions is to read their documentation and follow their examples - it usually doesn’t take more then 5-10 minutes to go through them and if you are coming from an RDMBS-only background many times these exercises can be an eye opener.

4.1.3. Trying Out The Samples

One can find various samples for key value stores in the dedicated example repo, at http://github.com/spring-projects/spring-data-keyvalue-examples. For Spring Data Redis, of interest is the retwisj sample, a Twitter-clone built on top of Redis which can be run locally or be deployed into the cloud. See its documentation, the following blog entry or thelive instance for more information.

4.2. Need Help?

If you encounter issues or you are just looking for advice, feel free to use one of the links below:

4.2.1. Community Support

The Spring Data tag on Stackoverflow is a message board for all Spring Data (not just Redis) users to share information and help each other. Note that registration is needed only for posting.

4.2.2. Professional Support

Professional, from-the-source support, with guaranteed response time, is available from Pivotal Software, Inc., the company behind Spring Data and Spring.

4.3. Following Development

For information on the Spring Data source code repository, nightly builds and snapshot artifacts please see the Spring Data home page.

You can help make Spring Data best serve the needs of the Spring community by interacting with developers on Stackoverflow at either spring-data or spring-data-redis.

If you encounter a bug or want to suggest an improvement, please create a ticket on the Spring Data issue tracker.

To stay up to date with the latest news and announcements in the Spring eco system, subscribe to the Spring CommunityPortal.

Lastly, you can follow the Spring blog or the project team (Thomas and Christoph) on Twitter.

Reference Documentation

Document structure

This part of the reference documentation explains the core functionality offered by Spring Data Redis.

Redis support introduces the Redis module feature set.

5. Redis support

One of the key value stores supported by Spring Data is Redis. To quote the project home page:

Redis is an advanced key-value store. It is similar to memcached but the dataset is not volatile, and values can be strings, exactly like in memcached, but also lists, sets, and ordered sets. All this data types can be manipulated with atomic operations to push/pop elements, add/remove elements, perform server side union, intersection, difference between sets, and so forth. Redis supports different kind of sorting abilities.

Spring Data Redis provides easy configuration and access to Redis from Spring applications. It offers both low-level and high-level abstractions for interacting with the store, freeing the user from infrastructural concerns.

5.1. Redis Requirements

Spring Redis requires Redis 2.6 or above and Java SE 6.0 or above . In terms of language bindings (or connectors), Spring Redis integrates with Jedis, JRedis (Deprecated since 1.7), SRP (Deprecated since 1.7) and Lettuce, four popular open source Java libraries for Redis. If you are aware of any other connector that we should be integrating with please send us feedback.

5.2. Redis Support High Level View

The Redis support provides several components (in order of dependencies):

For most tasks, the high-level abstractions and support services are the best choice. Note that at any point, one can move between layers - for example, it’s very easy to get a hold of the low level connection (or even the native library) to communicate directly with Redis.

5.3. Connecting to Redis

One of the first tasks when using Redis and Spring is to connect to the store through the IoC container. To do that, a Java connector (or binding) is required. No matter the library one chooses, there is only one set of Spring Data Redis API that one needs to use that behaves consistently across all connectors, namely theorg.springframework.data.redis.connection package and its RedisConnection and RedisConnectionFactoryinterfaces for working with and retrieving active connections to Redis.

5.3.1. RedisConnection and RedisConnectionFactory

RedisConnection provides the building block for Redis communication as it handles the communication with the Redis back-end. It also automatically translates the underlying connecting library exceptions to Spring’s consistent DAO exception hierarchy so one can switch the connectors without any code changes as the operation semantics remain the same.

For the corner cases where the native library API is required, RedisConnection provides a dedicated method getNativeConnection which returns the raw, underlying object used for communication.

Active RedisConnection s are created through RedisConnectionFactory. In addition, the factories act asPersistenceExceptionTranslator s, meaning once declared, they allow one to do transparent exception translation. For example, exception translation through the use of the @Repository annotation and AOP. For more information see the dedicated section in Spring Framework documentation.

Depending on the underlying configuration, the factory can return a new connection or an existing connection (in case a pool or shared native connection is used).

The easiest way to work with a RedisConnectionFactory is to configure the appropriate connector through the IoC container and inject it into the using class.

Unfortunately, currently, not all connectors support all Redis features. When invoking a method on the Connection API that is unsupported by the underlying library, an UnsupportedOperationException is thrown. This situation is likely to be fixed in the future, as the various connectors mature.

5.3.2. Configuring Jedis connector

Jedis is one of the connectors supported by the Spring Data Redis module through theorg.springframework.data.redis.connection.jedis package. In its simplest form, the Jedis configuration looks as follow:

For production use however, one might want to tweak the settings such as the host or password:

5.3.3. Configuring JRedis connector (Deprecated since 1.7)

JRedis is another popular, open-source connector supported by Spring Data Redis through theorg.springframework.data.redis.connection.jredis package.

A typical JRedis configuration can looks like this:

The configuration is quite similar to Jedis, with one notable exception. By default, the JedisConnectionFactory pools connections. In order to use a connection pool with JRedis, configure the JredisConnectionFactory with an instance ofJredisPool. For example:

5.3.4. Configuring SRP connector (Deprecated since 1.7)

SRP (an acronym for Sam’s Redis Protocol) is the third open-source connector supported by Spring Data Redis through theorg.springframework.data.redis.connection.srp package.

By now, its configuration is probably easy to guess:

Needless to say, the configuration is quite similar to that of the other connectors.

5.3.5. Configuring Lettuce connector

Lettuce is the fourth open-source connector supported by Spring Data Redis through theorg.springframework.data.redis.connection.lettuce package.

Its configuration is probably easy to guess:

There are also a few Lettuce-specific connection parameters that can be tweaked. By default, all LettuceConnection s created by the LettuceConnectionFactory share the same thread-safe native connection for all non-blocking and non-transactional operations. Set shareNativeConnection to false to use a dedicated connection each time.LettuceConnectionFactory can also be configured with a LettucePool to use for pooling blocking and transactional connections, or all connections if shareNativeConnection is set to false.

5.4. Redis Sentinel Support

For dealing with high available Redis there is support for Redis Sentinel using RedisSentinelConfiguration.

Please note that currently only Jedis and lettuce Lettuce support Redis Sentinel.

/**
 * jedis
 */
@Bean
public RedisConnectionFactory jedisConnectionFactory() {
  RedisSentinelConfiguration sentinelConfig = new RedisSentinelConfiguration() .master("mymaster")
  .sentinel("127.0.0.1", 26379) .sentinel("127.0.0.1", 26380);
  return new JedisConnectionFactory(sentinelConfig);
}

/**
 * lettuce
 */
@Bean
public RedisConnectionFactory lettuceConnectionFactory() {
  RedisSentinelConfiguration sentinelConfig = new RedisSentinelConfiguration().master("mymaster")
  .sentinel("127.0.0.1", 26379) .sentinel("127.0.0.1", 26380);
  return new LettuceConnectionFactory(sentinelConfig);
}

RedisSentinelConfiguration can also be defined via PropertySource. Configuration Properties spring.redis.sentinel.master: name of the master node. spring.redis.sentinel.nodes: Comma delimited list of host:port pairs.

Sometimes direct interaction with the one of the Sentinels is required. UsingRedisConnectionFactory.getSentinelConnection() or RedisConnection.getSentinelCommands() gives you access to the first active Sentinel configured.

5.5. Working with Objects through RedisTemplate

Most users are likely to use RedisTemplate and its coresponding package org.springframework.data.redis.core - the template is in fact the central class of the Redis module due to its rich feature set. The template offers a high-level abstraction for Redis interactions. While RedisConnection offers low level methods that accept and return binary values (byte arrays), the template takes care of serialization and connection management, freeing the user from dealing with such details.

Moreover, the template provides operations views (following the grouping from Redis command reference) that offer rich, generified interfaces for working against a certain type or certain key (through the KeyBound interfaces) as described below:

Table 1. Operational views

Interface	Description
Key Type Operations
ValueOperations	Redis string (or value) operations
ListOperations	Redis list operations
SetOperations	Redis set operations
ZSetOperations	Redis zset (or sorted set) operations
HashOperations	Redis hash operations
HyperLogLogOperations	Redis HyperLogLog operations like (pfadd, pfcount,…​)
Key Bound Operations
BoundValueOperations	Redis string (or value) key bound operations
BoundListOperations	Redis list key bound operations
BoundSetOperations	Redis set key bound operations
BoundZSetOperations	Redis zset (or sorted set) key bound operations
BoundHashOperations	Redis hash key bound operations

Once configured, the template is thread-safe and can be reused across multiple instances.

Out of the box, RedisTemplate uses a Java-based serializer for most of its operations. This means that any object written or read by the template will be serialized/deserialized through Java. The serialization mechanism can be easily changed on the template, and the Redis module offers several implementations available in theorg.springframework.data.redis.serializer package - see Serializers for more information. You can also set any of the serializers to null and use RedisTemplate with raw byte arrays by setting the enableDefaultSerializer property to false. Note that the template requires all keys to be non-null - values can be null as long as the underlying serializer accepts them; read the javadoc of each serializer for more information.

For cases where a certain template view is needed, declare the view as a dependency and inject the template: the container will automatically perform the conversion eliminating the opsFor[X] calls:

  
  
  
  ...

public class Example {

  // inject the actual template
  @Autowired
  private RedisTemplate template;

  // inject the template as ListOperations
  @Resource(name="redisTemplate")
  private ListOperations listOps;

  public void addLink(String userId, URL url) {
    listOps.leftPush(userId, url.toExternalForm());
  }
}

5.6. String-focused convenience classes

Since it’s quite common for the keys and values stored in Redis to be java.lang.String, the Redis modules provides two extensions to RedisConnection and RedisTemplate, respectively the StringRedisConnection (and itsDefaultStringRedisConnection implementation) and StringRedisTemplate as a convenient one-stop solution for intensive String operations. In addition to being bound to String keys, the template and the connection use theStringRedisSerializer underneath which means the stored keys and values are human readable (assuming the same encoding is used both in Redis and your code). For example:

  

  
  ...

public class Example {

  @Autowired
  private StringRedisTemplate redisTemplate;

  public void addLink(String userId, URL url) {
    redisTemplate.opsForList().leftPush(userId, url.toExternalForm());
  }
}

As with the other Spring templates, RedisTemplate and StringRedisTemplate allow the developer to talk directly to Redis through the RedisCallback interface. This gives complete control to the developer as it talks directly to theRedisConnection. Note that the callback receives an instance of StringRedisConnection when aStringRedisTemplate is used.

public void useCallback() {

  redisTemplate.execute(new RedisCallback