Refine Javadoc and source in caching infrastructure components.

Judiciously applies minor source code refinements, such as introducing named (local) variable object references to make it clearer the arguments that are being passed to caching method parameters, in favor of self-describing code with intent.

Closes #2742

Author: jxblum

src/main/java/org/springframework/data/redis/cache/RedisCache.java

@@ -62,6 +62,9 @@ public class RedisCache extends AbstractValueAdaptingCache {
 
 	static final byte[] BINARY_NULL_VALUE = RedisSerializer.java().serialize(NullValue.INSTANCE);
 
+	static final String CACHE_RETRIEVAL_UNSUPPORTED_OPERATION_EXCEPTION_MESSAGE =
+			"The Redis driver configured with RedisCache through RedisCacheWriter does not support CompletableFuture-based retrieval";
+
 	private final Lock lock = new ReentrantLock();
 
 	private final RedisCacheConfiguration cacheConfiguration;
@@ -71,16 +74,16 @@ public class RedisCache extends AbstractValueAdaptingCache {
 	private final String name;
 
 	/**
-	 * Create a new {@link RedisCache} with the given {@link String name} and {@link RedisCacheConfiguration}, using the
-	 * {@link RedisCacheWriter} to execute Redis commands supporting the cache operations.
+	 * Create a new {@link RedisCache} with the given {@link String name} and {@link RedisCacheConfiguration},
+	 * using the {@link RedisCacheWriter} to execute Redis commands supporting the cache operations.
 	 *
 	 * @param name {@link String name} for this {@link Cache}; must not be {@literal null}.
-	 * @param cacheWriter {@link RedisCacheWriter} used to perform {@link RedisCache} operations by executing the
-	 *          necessary Redis commands; must not be {@literal null}.
-	 * @param cacheConfiguration {@link RedisCacheConfiguration} applied to this {@link RedisCache} on creation; must not
-	 *          be {@literal null}.
+	 * @param cacheWriter {@link RedisCacheWriter} used to perform {@link RedisCache} operations
+	 * by executing the necessary Redis commands; must not be {@literal null}.
+	 * @param cacheConfiguration {@link RedisCacheConfiguration} applied to this {@link RedisCache} on creation;
+	 * must not be {@literal null}.
 	 * @throws IllegalArgumentException if either the given {@link RedisCacheWriter} or {@link RedisCacheConfiguration}
-	 *           are {@literal null} or the given {@link String} name for this {@link RedisCache} is {@literal null}.
+	 * are {@literal null} or the given {@link String} name for this {@link RedisCache} is {@literal null}.
 	 */
 	protected RedisCache(String name, RedisCacheWriter cacheWriter, RedisCacheConfiguration cacheConfiguration) {
 
@@ -98,28 +101,27 @@ protected RedisCache(String name, RedisCacheWriter cacheWriter, RedisCacheConfig
 	/**
 	 * Get the {@link RedisCacheConfiguration} used to configure this {@link RedisCache} on initialization.
 	 *
-	 * @return an immutable {@link RedisCacheConfiguration} used to configure this {@link RedisCache} on initialization;
-	 *         never {@literal null}.
+	 * @return an immutable {@link RedisCacheConfiguration} used to configure this {@link RedisCache} on initialization.
 	 */
 	public RedisCacheConfiguration getCacheConfiguration() {
 		return this.cacheConfiguration;
 	}
 
 	/**
-	 * Gets the configured {@link RedisCacheWriter} used to modify Redis for cache operations.
+	 * Gets the configured {@link RedisCacheWriter} used to adapt Redis for cache operations.
 	 *
-	 * @return the configured {@link RedisCacheWriter} used to modify Redis for cache operations.
+	 * @return the configured {@link RedisCacheWriter} used to adapt Redis for cache operations.
 	 */
 	protected RedisCacheWriter getCacheWriter() {
 		return this.cacheWriter;
 	}
 
 	/**
-	 * Gets the configured {@link ConversionService} used to convert {@link Object cache keys} to a {@link String} when
-	 * accessing entries in the cache.
+	 * Gets the configured {@link ConversionService} used to convert {@link Object cache keys} to a {@link String}
+	 * when accessing entries in the cache.
 	 *
-	 * @return the configured {@link ConversionService} used to convert {@link Object cache keys} to a {@link String} when
-	 *         accessing entries in the cache.
+	 * @return the configured {@link ConversionService} used to convert {@link Object cache keys} to a {@link String}
+	 * when accessing entries in the cache.
 	 * @see RedisCacheConfiguration#getConversionService()
 	 * @see #getCacheConfiguration()
 	 */
@@ -142,7 +144,7 @@ public RedisCacheWriter getNativeCache() {
 	 * <p>
 	 * Statistics are accumulated per cache instance and not from the backing Redis data store.
 	 *
-	 * @return statistics object for this {@link RedisCache}.
+	 * @return {@link CacheStatistics} object for this {@link RedisCache}.
 	 * @since 2.4
 	 */
 	public CacheStatistics getStatistics() {
@@ -173,8 +175,8 @@ private <T> T getSynchronized(Object key, Callable<T> valueLoader) {
 	}
 
 	/**
-	 * Loads the {@link Object} using the given {@link Callable valueLoader} and {@link #put(Object, Object) puts} the
-	 * {@link Object loaded value} in the cache.
+	 * Loads the {@link Object} using the given {@link Callable valueLoader} and {@link #put(Object, Object) puts}
+	 * the {@link Object loaded value} in the cache.
 	 *
 	 * @param <T> {@link Class type} of the loaded {@link Object cache value}.
 	 * @param key {@link Object key} mapped to the loaded {@link Object cache value}.
@@ -199,11 +201,13 @@ protected <T> T loadCacheValue(Object key, Callable<T> valueLoader) {
 	@Override
 	protected Object lookup(Object key) {
 
-		byte[] value = getCacheConfiguration().isTimeToIdleEnabled()
-				? getCacheWriter().get(getName(), createAndConvertCacheKey(key), getTimeToLive(key))
-				: getCacheWriter().get(getName(), createAndConvertCacheKey(key));
+		byte[] binaryKey = createAndConvertCacheKey(key);
+
+		byte[] binaryValue = getCacheConfiguration().isTimeToIdleEnabled()
+				? getCacheWriter().get(getName(), binaryKey, getTimeToLive(key))
+				: getCacheWriter().get(getName(), binaryKey);
 
-		return value != null ? deserializeCacheValue(value) : null;
+		return binaryValue != null ? deserializeCacheValue(binaryValue) : null;
 	}
 
 	private Duration getTimeToLive(Object key) {
@@ -219,8 +223,12 @@ public void put(Object key, @Nullable Object value) {
 
 		Object cacheValue = processAndCheckValue(value);
 
-		getCacheWriter().put(getName(), createAndConvertCacheKey(key), serializeCacheValue(cacheValue),
-				getTimeToLive(key, value));
+		byte[] binaryKey = createAndConvertCacheKey(key);
+		byte[] binaryValue = serializeCacheValue(cacheValue);
+
+		Duration timeToLive = getTimeToLive(key, value);
+
+		getCacheWriter().put(getName(), binaryKey, binaryValue, timeToLive);
 	}
 
 	@Override
@@ -232,8 +240,11 @@ public ValueWrapper putIfAbsent(Object key, @Nullable Object value) {
 			return get(key);
 		}
 
-		byte[] result = getCacheWriter().putIfAbsent(getName(), createAndConvertCacheKey(key),
-				serializeCacheValue(cacheValue), getTimeToLive(key, value));
+		Duration timeToLive = getTimeToLive(key, value);
+
+		byte[] binaryKey = createAndConvertCacheKey(key);
+		byte[] binaryValue = serializeCacheValue(cacheValue);
+		byte[] result = getCacheWriter().putIfAbsent(getName(), binaryKey, binaryValue, timeToLive);
 
 		return result != null ? new SimpleValueWrapper(fromStoreValue(deserializeCacheValue(result))) : null;
 	}
@@ -273,8 +284,7 @@ public void evict(Object key) {
 	public CompletableFuture<?> retrieve(Object key) {
 
 		if (!getCacheWriter().supportsAsyncRetrieve()) {
-			throw new UnsupportedOperationException(
-					"The Redis driver configured with RedisCache through RedisCacheWriter does not support CompletableFuture-based retrieval");
+			throw new UnsupportedOperationException(CACHE_RETRIEVAL_UNSUPPORTED_OPERATION_EXCEPTION_MESSAGE);
 		}
 
 		return retrieveValue(key).thenApply(this::nullSafeDeserializedStoreValue);
@@ -285,27 +295,28 @@ public CompletableFuture<?> retrieve(Object key) {
 	public <T> CompletableFuture<T> retrieve(Object key, Supplier<CompletableFuture<T>> valueLoader) {
 
 		if (!getCacheWriter().supportsAsyncRetrieve()) {
-			throw new UnsupportedOperationException(
-					"The Redis driver configured with RedisCache through RedisCacheWriter does not support CompletableFuture-based retrieval");
+			throw new UnsupportedOperationException(CACHE_RETRIEVAL_UNSUPPORTED_OPERATION_EXCEPTION_MESSAGE);
 		}
 
-		return retrieveValue(key) //
-				.thenCompose(bytes -> {
+		return retrieveValue(key).thenCompose(bytes -> {
+
+			if (bytes != null) {
+				return CompletableFuture.completedFuture((T) nullSafeDeserializedStoreValue(bytes));
+			}
+
+			return valueLoader.get().thenCompose(value -> {
 
-					if (bytes != null) {
-						return CompletableFuture.completedFuture((T) nullSafeDeserializedStoreValue(bytes));
-					}
+				Object cacheValue = processAndCheckValue(value);
 
-					return valueLoader.get().thenCompose(value -> {
+				byte[] binaryKey = createAndConvertCacheKey(key);
+				byte[] binaryValue = serializeCacheValue(cacheValue);
 
-						Object cacheValue = processAndCheckValue(value);
+				Duration timeToLive = getTimeToLive(key, cacheValue);
 
-						return getCacheWriter()
-								.store(getName(), createAndConvertCacheKey(key), serializeCacheValue(cacheValue),
-										getTimeToLive(key, cacheValue)) //
-								.thenApply(v -> value);
-					});
-				});
+				return getCacheWriter().store(getName(), binaryKey, binaryValue, timeToLive)
+						.thenApply(v -> value);
+			});
+		});
 	}
 
 	private Object processAndCheckValue(@Nullable Object value) {
@@ -403,8 +414,8 @@ protected String createCacheKey(Object key) {
 	 */
 	protected String convertKey(Object key) {
 
-		if (key instanceof String) {
-			return (String) key;
+		if (key instanceof String stringKey) {
+			return stringKey;
 		}
 
 		TypeDescriptor source = TypeDescriptor.forObject(key);
@@ -429,9 +440,8 @@ protected String convertKey(Object key) {
 			return key.toString();
 		}
 
-		String message = String.format(
-				"Cannot convert cache key %s to String; Please register a suitable Converter"
-						+ " via 'RedisCacheConfiguration.configureKeyConverters(...)' or override '%s.toString()'",
+		String message = String.format("Cannot convert cache key %s to String; Please register a suitable Converter"
+				+ " via 'RedisCacheConfiguration.configureKeyConverters(...)' or override '%s.toString()'",
 				source, key.getClass().getName());
 
 		throw new IllegalStateException(message);