Polishing.

Tweak wording around thread-safety. Include notices in connection factories.

Reformat asciidoc.

See #2653
Original pull request: #2667

Author: mp911de

src/main/asciidoc/reference/redis.adoc

@@ -80,9 +80,15 @@ NOTE: For the corner cases where the native library API is required, `RedisConne
 
 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:  `RedisConnection` classes 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.
+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).
 

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

@@ -28,6 +28,9 @@
  * {@link RedisClusterNode} can be obtained from {@link #clusterGetNodes()} or it can be constructed using either
  * {@link RedisClusterNode#getHost() host} and {@link RedisClusterNode#getPort()} or the {@link RedisClusterNode#getId()
  * node Id}.
+ * <p>
+ * {@link RedisClusterConnection Redis connections}, unlike perhaps their underlying native connection are not
+ * Thread-safe and should not be shared across multiple threads.
  *
  * @author Christoph Strobl
  * @author Mark Paluch

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

@@ -20,13 +20,13 @@
 import org.springframework.dao.DataAccessException;
 
 /**
- * A connection to a Redis server. Acts as an common abstraction across various Redis client libraries (or drivers).
+ * 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.
+ * {@link RedisConnection Redis connections}, unlike perhaps their underlying native connection are not Thread-safe and
+ * should not be shared across multiple threads.
  *
  * @author Costin Leau
  * @author Christoph Strobl

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

@@ -35,7 +35,6 @@
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
-
 import org.springframework.beans.DirectFieldAccessor;
 import org.springframework.beans.PropertyAccessor;
 import org.springframework.dao.DataAccessException;
@@ -61,6 +60,8 @@
  * {@link RedisClusterConnection} implementation on top of {@link JedisCluster}.<br/>
  * Uses the native {@link JedisCluster} api where possible and falls back to direct node communication using
  * {@link Jedis} where needed.
+ * <p>
+ * This class is not Thread-safe and instances should not be shared across threads.
  *
  * @author Christoph Strobl
  * @author Mark Paluch

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

@@ -41,7 +41,6 @@
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
-
 import org.springframework.core.convert.converter.Converter;
 import org.springframework.dao.DataAccessException;
 import org.springframework.dao.InvalidDataAccessApiUsageException;
@@ -60,10 +59,7 @@
 /**
  * {@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.
+ * This class is not Thread-safe and instances should not be shared across threads.
  *
  * @author Costin Leau
  * @author Jennifer Hickey

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

@@ -75,6 +75,11 @@
  * <p>
  * This connection factory must be {@link #afterPropertiesSet() initialized} prior to {@link #getConnection obtaining
  * connections}.
+ * <p>
+ * Note that {@link JedisConnection} and its {@link JedisClusterConnection clustered variant} are not Thread-safe and
+ * instances should not be shared across threads. Refer to the
+ * <a href="https://github.com/redis/jedis/wiki/Getting-started#using-jedis-in-a-multithreaded-environment">Jedis
+ * documentation</a> for guidance on configuring Jedis in a multithreaded environment.
  *
  * @author Costin Leau
  * @author Thomas Darimont

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

@@ -32,7 +32,6 @@
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
-
 import org.springframework.beans.factory.DisposableBean;
 import org.springframework.dao.DataAccessException;
 import org.springframework.dao.InvalidDataAccessApiUsageException;
@@ -53,6 +52,13 @@
 /**
  * {@code RedisClusterConnection} implementation on top of <a href="https://github.com/mp911de/lettuce">Lettuce</a>
  * Redis client.
+ * <p>
+ * While the underlying Lettuce {@literal RedisClient} and {@literal StatefulRedisConnection} instances used by
+ * {@link LettuceClusterConnection} are Thread-safe, this class itself is not Thread-safe. Therefore, instances of
+ * {@link LettuceClusterConnection} 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 Christoph Strobl
  * @author Mark Paluch
@@ -486,7 +492,6 @@ public void multi() {
 		throw new InvalidDataAccessApiUsageException("MULTI is currently not supported in cluster mode");
 	}
 
-
 	public ClusterCommandExecutor getClusterCommandExecutor() {
 		return clusterCommandExecutor;
 	}

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

@@ -80,12 +80,12 @@
  * {@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.
+ * 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

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

@@ -68,8 +68,10 @@
 /**
  * Connection factory creating <a href="https://github.com/mp911de/lettuce">Lettuce</a>-based connections.
  * <p>
- * This factory creates a new {@link LettuceConnection} on each call to {@link #getConnection()}. Multiple
- * {@link LettuceConnection}s share a single thread-safe native connection by default.
+ * This factory creates a new {@link LettuceConnection} on each call to {@link #getConnection()}. While multiple
+ * {@link LettuceConnection}s share a single thread-safe native connection by default, {@link LettuceConnection} and its
+ * {@link LettuceClusterConnection clustered variant} are not Thread-safe and instances should not be shared across
+ * threads.
  * <p>
  * The shared native connection is never closed by {@link LettuceConnection}, therefore it is not validated by default
  * on {@link #getConnection()}. Use {@link #setValidateConnection(boolean)} to change this behavior if necessary. If