From 050beebc740187e4fc5cf7ca8520df69e10196a0 Mon Sep 17 00:00:00 2001
From: John Blum <jblum@vmware.com>
Date: Tue, 23 May 2023 08:46:06 -0700
Subject: [PATCH] Edit and cleanup Javadoc.

Resolves #2586
---
 .../data/redis/cache/RedisCache.java          |  6 ++-
 .../redis/cache/RedisCacheConfiguration.java  |  6 +--
 .../data/redis/connection/RedisCommands.java  | 16 ++++----
 .../connection/RedisConnectionFactory.java    | 39 ++++++++++---------
 .../data/redis/core/RedisCallback.java        | 15 ++++---
 .../AbstractConnectionIntegrationTests.java   | 35 +++++++++++------
 6 files changed, 71 insertions(+), 46 deletions(-)

diff --git a/src/main/java/org/springframework/data/redis/cache/RedisCache.java b/src/main/java/org/springframework/data/redis/cache/RedisCache.java
index f6877da44..5c7193b52 100644
--- a/src/main/java/org/springframework/data/redis/cache/RedisCache.java
+++ b/src/main/java/org/springframework/data/redis/cache/RedisCache.java
@@ -41,7 +41,7 @@ import org.springframework.util.ReflectionUtils;
 
 /**
  * {@link org.springframework.cache.Cache} implementation using for Redis as the underlying store for cache data.
- *
+ * <p>
  * Use {@link RedisCacheManager} to create {@link RedisCache} instances.
  *
  * @author Christoph Strobl
@@ -52,6 +52,7 @@ import org.springframework.util.ReflectionUtils;
  * @see org.springframework.cache.support.AbstractValueAdaptingCache
  * @since 2.0
  */
+@SuppressWarnings("unused")
 public class RedisCache extends AbstractValueAdaptingCache {
 
 	private static final byte[] BINARY_NULL_VALUE = RedisSerializer.java().serialize(NullValue.INSTANCE);
@@ -136,7 +137,8 @@ public class RedisCache extends AbstractValueAdaptingCache {
 	}
 
 	@SuppressWarnings("unchecked")
-	private synchronized @Nullable <T> T getSynchronized(Object key, Callable<T> valueLoader) {
+	@Nullable
+	private synchronized <T> T getSynchronized(Object key, Callable<T> valueLoader) {
 
 		ValueWrapper result = get(key);
 
diff --git a/src/main/java/org/springframework/data/redis/cache/RedisCacheConfiguration.java b/src/main/java/org/springframework/data/redis/cache/RedisCacheConfiguration.java
index 74c73cc28..da9b06215 100644
--- a/src/main/java/org/springframework/data/redis/cache/RedisCacheConfiguration.java
+++ b/src/main/java/org/springframework/data/redis/cache/RedisCacheConfiguration.java
@@ -33,7 +33,7 @@ import org.springframework.util.Assert;
 /**
  * Immutable {@link RedisCacheConfiguration} used to customize {@link RedisCache} behaviour, such as caching
  * {@literal null} values, computing cache key prefixes and handling binary serialization.
- *
+ * <p>
  * Start with {@link RedisCacheConfiguration#defaultCacheConfig()} and customize {@link RedisCache} behaviour
  * from that point on.
  *
@@ -344,9 +344,9 @@ public class RedisCacheConfiguration {
 
 	/**
 	 * Registers default cache {@link Converter key converters}.
-	 *
+	 * <p>
 	 * The following converters get registered:
-	 *
+	 * <p>
 	 * <ul>
 	 * <li>{@link String} to {@link byte byte[]} using UTF-8 encoding.</li>
 	 * <li>{@link SimpleKey} to {@link String}</li>
diff --git a/src/main/java/org/springframework/data/redis/connection/RedisCommands.java b/src/main/java/org/springframework/data/redis/connection/RedisCommands.java
index 4ecb7b485..a185a0ea8 100644
--- a/src/main/java/org/springframework/data/redis/connection/RedisCommands.java
+++ b/src/main/java/org/springframework/data/redis/connection/RedisCommands.java
@@ -18,7 +18,7 @@ package org.springframework.data.redis.connection;
 import org.springframework.lang.Nullable;
 
 /**
- * Interface for the commands supported by Redis.
+ * Interface defining the commands supported by Redis.
  *
  * @author Costin Leau
  * @author Christoph Strobl
@@ -29,14 +29,16 @@ public interface RedisCommands extends RedisKeyCommands, RedisStringCommands, Re
 		RedisServerCommands, RedisStreamCommands, RedisScriptingCommands, RedisGeoCommands, RedisHyperLogLogCommands {
 
 	/**
-	 * 'Native' or 'raw' execution of the given command along-side the given arguments. The command is executed as is,
-	 * with as little 'interpretation' as possible - it is up to the caller to take care of any processing of arguments or
-	 * the result.
+	 * {@literal Native} or {@literal raw} execution of the given Redis command along with the given arguments.
+	 * <p>
+	 * The command is executed as is, with as little interpretation as possible - it is up to the caller to take care
+	 * of any processing of arguments or the result.
 	 *
-	 * @param command Command to execute. must not be {@literal null}.
-	 * @param args Possible command arguments (may be empty).
-	 * @return execution result. Can be {@literal null}.
+	 * @param command Redis {@link String command} to execute; must not be {@literal null}.
+	 * @param args optional array of command arguments; may be empty;
+	 * @return the execution result; may be {@literal null}.
 	 */
 	@Nullable
 	Object execute(String command, byte[]... args);
+
 }
diff --git a/src/main/java/org/springframework/data/redis/connection/RedisConnectionFactory.java b/src/main/java/org/springframework/data/redis/connection/RedisConnectionFactory.java
index acee03eef..5a14fd8e6 100644
--- a/src/main/java/org/springframework/data/redis/connection/RedisConnectionFactory.java
+++ b/src/main/java/org/springframework/data/redis/connection/RedisConnectionFactory.java
@@ -13,7 +13,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 package org.springframework.data.redis.connection;
 
 import org.springframework.dao.support.PersistenceExceptionTranslator;
@@ -23,45 +22,49 @@ import org.springframework.dao.support.PersistenceExceptionTranslator;
  *
  * @author Costin Leau
  * @author Christoph Strobl
+ * @author John Blum
  */
 public interface RedisConnectionFactory extends PersistenceExceptionTranslator {
 
 	/**
-	 * Provides a suitable connection for interacting with Redis.
+	 * Returns a suitable {@link RedisConnection connection} for interacting with Redis.
 	 *
-	 * @return connection for interacting with Redis.
-	 * @throws IllegalStateException if the connection factory requires initialization and the factory was not yet
-	 *           initialized.
+	 * @return {@link RedisConnection connection} for interacting with Redis.
+	 * @throws IllegalStateException if the connection factory requires initialization and the factory has not yet
+	 * been initialized.
 	 */
 	RedisConnection getConnection();
 
 	/**
-	 * Provides a suitable connection for interacting with Redis Cluster.
+	 * Returns a suitable {@link RedisClusterConnection connection} for interacting with Redis Cluster.
 	 *
-	 * @return
-	 * @throws IllegalStateException if the connection factory requires initialization and the factory was not yet
-	 *           initialized.
+	 * @return a {@link RedisClusterConnection connection} for interacting with Redis Cluster.
+	 * @throws IllegalStateException if the connection factory requires initialization and the factory has not yet
+	 * been initialized.
 	 * @since 1.7
 	 */
 	RedisClusterConnection getClusterConnection();
 
 	/**
-	 * Specifies if pipelined results should be converted to the expected data type. If false, results of
-	 * {@link RedisConnection#closePipeline()} and {RedisConnection#exec()} will be of the type returned by the underlying
-	 * driver This method is mostly for backwards compatibility with 1.0. It is generally always a good idea to allow
-	 * results to be converted and deserialized. In fact, this is now the default behavior.
+	 * Specifies if pipelined results should be converted to the expected data type.
+	 * <p>
+	 * If {@literal false}, results of {@link RedisConnection#closePipeline()} and {@link RedisConnection#exec()}
+	 * will be of the type returned by the underlying driver. This method is mostly for backwards compatibility
+	 * with {@literal 1.0}. It is generally always a good idea to allow results to be converted and deserialized.
+	 * In fact, this is now the default behavior.
 	 *
-	 * @return Whether or not to convert pipeline and tx results
+	 * @return a boolen indicating whether to convert pipeline and transaction results.
 	 */
 	boolean getConvertPipelineAndTxResults();
 
 	/**
-	 * Provides a suitable connection for interacting with Redis Sentinel.
+	 * Returns a suitable {@link RedisSentinelConnection connection} for interacting with Redis Sentinel.
 	 *
-	 * @return connection for interacting with Redis Sentinel.
-	 * @throws IllegalStateException if the connection factory requires initialization and the factory was not yet
-	 *           initialized.
+	 * @return a {@link RedisSentinelConnection connection} for interacting with Redis Sentinel.
+	 * @throws IllegalStateException if the connection factory requires initialization and the factory has not yet
+	 * been initialized.
 	 * @since 1.4
 	 */
 	RedisSentinelConnection getSentinelConnection();
+
 }
diff --git a/src/main/java/org/springframework/data/redis/core/RedisCallback.java b/src/main/java/org/springframework/data/redis/core/RedisCallback.java
index da1f8387c..1faadc0c4 100644
--- a/src/main/java/org/springframework/data/redis/core/RedisCallback.java
+++ b/src/main/java/org/springframework/data/redis/core/RedisCallback.java
@@ -25,17 +25,22 @@ import org.springframework.lang.Nullable;
  * {@code get/set/trim etc...}.
  *
  * @author Costin Leau
+ * @author John Blum
  */
 public interface RedisCallback<T> {
 
 	/**
-	 * Gets called by {@link RedisTemplate} with an active Redis connection. Does not need to care about activating or
-	 * closing the connection or handling exceptions.
+	 * Method called by {@link RedisTemplate} with an active {@link RedisConnection}.
+	 * <p>
+	 * Callback code need not care about activating/opening or closing the {@link RedisConnection},
+	 * nor handling {@link Exception exceptions}.
 	 *
-	 * @param connection active Redis connection
-	 * @return a result object or {@code null} if none
-	 * @throws DataAccessException
+	 * @param connection active {@link RedisConnection Redis connection}.
+	 * @return the {@link Object result} of the operation performed in the callback or {@code null}.
+	 * @throws DataAccessException if the operation performed by the callback fails to execute in the context of Redis
+	 * using the given {@link RedisConnection}.
 	 */
 	@Nullable
 	T doInRedis(RedisConnection connection) throws DataAccessException;
+
 }
diff --git a/src/test/java/org/springframework/data/redis/connection/AbstractConnectionIntegrationTests.java b/src/test/java/org/springframework/data/redis/connection/AbstractConnectionIntegrationTests.java
index a343ab4af..b6b12293e 100644
--- a/src/test/java/org/springframework/data/redis/connection/AbstractConnectionIntegrationTests.java
+++ b/src/test/java/org/springframework/data/redis/connection/AbstractConnectionIntegrationTests.java
@@ -131,6 +131,18 @@ public abstract class AbstractConnectionIntegrationTests {
 
 	protected RedisConnection byteConnection;
 
+	private boolean isJedisOrLettuceConnection(RedisConnectionFactory connectionFactory) {
+		return ConnectionUtils.isJedis(connectionFactory) || ConnectionUtils.isLettuce(connectionFactory);
+	}
+
+	private boolean isNotJedisOrLettuceConnection(RedisConnectionFactory connectionFactory) {
+		return !isJedisOrLettuceConnection(connectionFactory);
+	}
+
+	private boolean isPipelinedOrQueueingConnection(RedisConnection connection) {
+		return connection.isPipelined() || connection.isQueueing();
+	}
+
 	@BeforeEach
 	public void setUp() {
 
@@ -2595,12 +2607,12 @@ public abstract class AbstractConnectionIntegrationTests {
 	@Test // DATAREDIS-290
 	void scanShouldReadEntireValueRange() {
 
-		if (!ConnectionUtils.isJedis(connectionFactory) && !ConnectionUtils.isLettuce(connectionFactory)) {
+		if (isNotJedisOrLettuceConnection(connectionFactory)) {
 			throw new AssumptionViolatedException("SCAN is only available for jedis and lettuce");
 		}
 
-		if (connection.isPipelined() || connection.isQueueing()) {
-			throw new AssumptionViolatedException("SCAN is only available in non pipeline | queue mode");
+		if (isPipelinedOrQueueingConnection(connection)) {
+			throw new AssumptionViolatedException("SCAN is only available in non-pipeline | non-queueing mode");
 		}
 
 		connection.set("spring", "data");
@@ -2626,8 +2638,9 @@ public abstract class AbstractConnectionIntegrationTests {
 	@EnabledOnRedisVersion("6.0")
 	void scanWithType() {
 
-		assumeThat(connection.isPipelined() || connection.isQueueing())
-				.describedAs("SCAN is only available in non pipeline | queue mode").isFalse();
+		assumeThat(isPipelinedOrQueueingConnection(connection))
+				.describedAs("SCAN is only available in non-pipeline | non-queueing mode")
+				.isFalse();
 
 		connection.set("key", "data");
 		connection.lPush("list", "foo");
@@ -2670,11 +2683,11 @@ public abstract class AbstractConnectionIntegrationTests {
 	@Test // DATAREDIS-306
 	void zScanShouldReadEntireValueRange() {
 
-		if (!ConnectionUtils.isJedis(connectionFactory) && !ConnectionUtils.isLettuce(connectionFactory)) {
+		if (isNotJedisOrLettuceConnection(connectionFactory)) {
 			throw new AssumptionViolatedException("ZSCAN is only available for jedis and lettuce");
 		}
 
-		if (connection.isPipelined() || connection.isQueueing()) {
+		if (isPipelinedOrQueueingConnection(connection)) {
 			throw new AssumptionViolatedException("ZSCAN is only available in non pipeline | queue mode");
 		}
 
@@ -2701,11 +2714,11 @@ public abstract class AbstractConnectionIntegrationTests {
 	@Test // DATAREDIS-304
 	void sScanShouldReadEntireValueRange() {
 
-		if (!ConnectionUtils.isJedis(connectionFactory) && !ConnectionUtils.isLettuce(connectionFactory)) {
+		if (isNotJedisOrLettuceConnection(connectionFactory)) {
 			throw new AssumptionViolatedException("SCAN is only available for jedis and lettuce");
 		}
 
-		if (connection.isPipelined() || connection.isQueueing()) {
+		if (isPipelinedOrQueueingConnection(connection)) {
 			throw new AssumptionViolatedException("SCAN is only available in non pipeline | queue mode");
 		}
 
@@ -2726,11 +2739,11 @@ public abstract class AbstractConnectionIntegrationTests {
 	@Test // DATAREDIS-305
 	void hScanShouldReadEntireValueRange() {
 
-		if (!ConnectionUtils.isJedis(connectionFactory) && !ConnectionUtils.isLettuce(connectionFactory)) {
+		if (isNotJedisOrLettuceConnection(connectionFactory)) {
 			throw new AssumptionViolatedException("HSCAN is only available for jedis and lettuce");
 		}
 
-		if (connection.isPipelined() || connection.isQueueing()) {
+		if (isPipelinedOrQueueingConnection(connection)) {
 			throw new AssumptionViolatedException("HSCAN is only available in non pipeline | queue mode");
 		}