Edit ref docs and Javadoc for connection classes to clearly state the Thread-safety guarantees.

Closes #2653
Original pull request: #2667

Author: jxblum

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 <<redis:template,documentation>> 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.

src/main/java/org/springframework/data/redis/connection/RedisConnection.java

@@ -23,6 +23,10 @@
  * A connection to a Redis server. Acts as an common abstraction across various Redis client libraries (or drivers).
  * 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.
+ * <p>
+ * 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

src/main/java/org/springframework/data/redis/connection/jedis/JedisConnection.java

@@ -59,6 +59,11 @@
 
 /**
  * {@code RedisConnection} implementation on top of <a href="https://github.com/redis/jedis">Jedis</a> library.
+ * <p>
+ * 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
+ * <a href="https://github.com/redis/jedis/wiki/Getting-started#using-jedis-in-a-multithreaded-environment">documented</a>
+ * 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 {
 

src/main/java/org/springframework/data/redis/connection/lettuce/LettuceConnection.java

@@ -79,6 +79,13 @@
 /**
  * {@code RedisConnection} implementation on top of <a href="https://github.com/mp911de/lettuce">Lettuce</a> Redis
  * client.
+ * <p>
+ * 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 {