diff --git a/pom.xml b/pom.xml index 2a4c209133..96247c0c44 100644 --- a/pom.xml +++ b/pom.xml @@ -5,7 +5,7 @@ org.springframework.data spring-data-redis - 3.2.0-SNAPSHOT + 3.2.0-GH-2653-SNAPSHOT Spring Data Redis Spring Data module for Redis diff --git a/src/main/asciidoc/reference/redis.adoc b/src/main/asciidoc/reference/redis.adoc index 7ee170d91c..196eee4b0c 100644 --- a/src/main/asciidoc/reference/redis.adoc +++ b/src/main/asciidoc/reference/redis.adoc @@ -74,12 +74,16 @@ One of the first tasks when using Redis and Spring is to connect to the store th [[redis:connectors:connection]] === RedisConnection and RedisConnectionFactory -`RedisConnection` provides the core 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 {spring-framework-reference}/data-access.html#dao-exceptions[hierarchy] so that you can switch the connectors without any code changes, as the operation semantics remain the same. +`RedisConnection` provides the core building block for Redis communication, as it handles the communication with the Redis backend. It also automatically translates underlying connecting library exceptions to Spring's consistent {spring-framework-reference}/data-access.html#dao-exceptions[DAO exception hierarchy] so that you can switch connectors without any code changes, as the operation semantics remain the same. NOTE: For the corner cases where the native library API is required, `RedisConnection` provides a dedicated method (`getNativeConnection`) that returns the raw, underlying object used for communication. Active `RedisConnection` objects are created through `RedisConnectionFactory`. In addition, the factory acts as `PersistenceExceptionTranslator` objects, meaning that, once declared, they let you do transparent exception translation. For example, you can do exception translation through the use of the `@Repository` annotation and AOP. For more information, see the dedicated {spring-framework-reference}/data-access.html#orm-exception-translation[section] in the Spring Framework documentation. +WARNING: `RedisConnection` classes, such as `JedisConnection` and `LettuceConnection`, are **not** Thread-safe. While the underlying native connection, such as Lettuce's `StatefulRedisConnection`, may be Thread-safe, Spring Data Redis's `LettuceConnection` class itself is not Thread-safe. Therefore, you should **not** share instances of a `RedisConnection` across multiple Threads. This is especially true for transactional, or blocking Redis operations and commands, such as `BLPOP`. In transactional and pipelining operations, for instance, `RedisConnection` holds onto unguarded mutable state to complete the operation correctly, thereby making it unsafe to use with multiple Threads. This is by design. + +TIP: If you need to share (stateful) Redis resources, like connections, across multiple Threads, for performance reasons or otherwise, then you should acquire the native connection and use the Redis client library (driver) API directly. Alternatively, you can use the `RedisTemplate`, which acquires and manages connections for operations (and Redis commands) in a Thread-safe manner. See <> on `RedisTemplate` for more details. + NOTE: Depending on the underlying configuration, the factory can return a new connection or an existing connection (when 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. diff --git a/src/main/java/org/springframework/data/redis/connection/RedisConnection.java b/src/main/java/org/springframework/data/redis/connection/RedisConnection.java index e5ddcba127..3be1729388 100644 --- a/src/main/java/org/springframework/data/redis/connection/RedisConnection.java +++ b/src/main/java/org/springframework/data/redis/connection/RedisConnection.java @@ -27,6 +27,10 @@ *

* Additionally, performs exception translation between the underlying Redis client library and Spring DAO exceptions. * The methods follow as much as possible the Redis names and conventions. + *

+ * Spring Data Redis {@link RedisConnection connections}, unlike perhaps their underlying native connection (for example: + * the Lettuce {@literal StatefulRedisConnection}) are not Thread-safe. Please refer to the corresponding the Javadoc + * for Redis client library (driver) specific connections provided by Spring Data Redis for more details. * * @author Costin Leau * @author Christoph Strobl diff --git a/src/main/java/org/springframework/data/redis/connection/jedis/JedisConnection.java b/src/main/java/org/springframework/data/redis/connection/jedis/JedisConnection.java index 61231fd0b5..850210cd7d 100644 --- a/src/main/java/org/springframework/data/redis/connection/jedis/JedisConnection.java +++ b/src/main/java/org/springframework/data/redis/connection/jedis/JedisConnection.java @@ -59,6 +59,11 @@ /** * {@code RedisConnection} implementation on top of Jedis library. + *

+ * WARNING: The {@link JedisConnection} class is not Thread-safe. This class requires and uses a + * {@literal Jedis} instance from the Jedis client library (driver), which is very clearly + * documented + * as not Thread-safe. * * @author Costin Leau * @author Jennifer Hickey @@ -72,6 +77,8 @@ * @author Ninad Divadkar * @author Guy Korland * @author Dengliming + * @author John Blum + * @see redis.clients.jedis.Jedis */ public class JedisConnection extends AbstractRedisConnection { diff --git a/src/main/java/org/springframework/data/redis/connection/lettuce/LettuceConnection.java b/src/main/java/org/springframework/data/redis/connection/lettuce/LettuceConnection.java index ddef4a1df6..f0ed270395 100644 --- a/src/main/java/org/springframework/data/redis/connection/lettuce/LettuceConnection.java +++ b/src/main/java/org/springframework/data/redis/connection/lettuce/LettuceConnection.java @@ -79,6 +79,13 @@ /** * {@code RedisConnection} implementation on top of Lettuce Redis * client. + *

+ * WARNING: While the underlying Lettuce {@literal RedisClient} and {@literal StatefulRedisConnection} instances used by + * {@link LettuceConnection} are Thread-safe, this class itself is not Thread-safe. Therefore, instances of {@link LettuceConnection} + * should not be shared across multiple Threads when executing Redis commands and other operations. If optimal performance + * is required by your application(s), then we recommend direct access to the low-level, API provided by the underlying + * Lettuce client library (driver), where such Thread-safety guarantees can be made. Simply call {@link #getNativeConnection()} + * and use the native resource as required. * * @author Costin Leau * @author Jennifer Hickey @@ -89,6 +96,7 @@ * @author Ninad Divadkar * @author Tamil Selvan * @author ihaohong + * @author John Blum */ public class LettuceConnection extends AbstractRedisConnection {