Polishing

spring-context-support/src/main/java/org/springframework/cache/jcache/interceptor/AbstractCacheInterceptor.java

 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2019 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -59,7 +59,7 @@ abstract class AbstractCacheInterceptor<O extends AbstractJCacheOperation<A>, A
 	/**
 	 * Resolve the cache to use.
 	 * @param context the invocation context
-	 * @return the cache to use (never null)
+	 * @return the cache to use (never {@code null})
 	 */
 	protected Cache resolveCache(CacheOperationInvocationContext<O> context) {
 		Collection<? extends Cache> caches = context.getOperation().getCacheResolver().resolveCaches(context);
@@ -73,7 +73,7 @@ abstract class AbstractCacheInterceptor<O extends AbstractJCacheOperation<A>, A
 	/**
 	 * Convert the collection of caches in a single expected element.
 	 * <p>Throw an {@link IllegalStateException} if the collection holds more than one element
-	 * @return the single element or {@code null} if the collection is empty
+	 * @return the single element, or {@code null} if the collection is empty
 	 */
 	@Nullable
 	static Cache extractFrom(Collection<? extends Cache> caches) {

spring-context-support/src/main/java/org/springframework/cache/jcache/interceptor/CacheRemoveAllInterceptor.java

 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2019 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -42,7 +42,6 @@ class CacheRemoveAllInterceptor extends AbstractCacheInterceptor<CacheRemoveAllO
 			CacheOperationInvocationContext<CacheRemoveAllOperation> context, CacheOperationInvoker invoker) {
 
 		CacheRemoveAllOperation operation = context.getOperation();
-
 		boolean earlyRemove = operation.isEarlyRemove();
 		if (earlyRemove) {
 			removeAll(context);
@@ -67,8 +66,8 @@ class CacheRemoveAllInterceptor extends AbstractCacheInterceptor<CacheRemoveAllO
 	protected void removeAll(CacheOperationInvocationContext<CacheRemoveAllOperation> context) {
 		Cache cache = resolveCache(context);
 		if (logger.isTraceEnabled()) {
-			logger.trace("Invalidating entire cache '" + cache.getName() + "' for operation "
-					+ context.getOperation());
+			logger.trace("Invalidating entire cache '" + cache.getName() + "' for operation " +
+					context.getOperation());
 		}
 		doClear(cache);
 	}

spring-context-support/src/main/java/org/springframework/cache/jcache/interceptor/CacheRemoveEntryInterceptor.java

 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2019 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -42,7 +42,6 @@ class CacheRemoveEntryInterceptor extends AbstractKeyCacheInterceptor<CacheRemov
 			CacheOperationInvocationContext<CacheRemoveOperation> context, CacheOperationInvoker invoker) {
 
 		CacheRemoveOperation operation = context.getOperation();
-
 		boolean earlyRemove = operation.isEarlyRemove();
 		if (earlyRemove) {
 			removeValue(context);
@@ -68,8 +67,8 @@ class CacheRemoveEntryInterceptor extends AbstractKeyCacheInterceptor<CacheRemov
 		Object key = generateKey(context);
 		Cache cache = resolveCache(context);
 		if (logger.isTraceEnabled()) {
-			logger.trace("Invalidating key [" + key + "] on cache '" + cache.getName()
-					+ "' for operation " + context.getOperation());
+			logger.trace("Invalidating key [" + key + "] on cache '" + cache.getName() +
+					"' for operation " + context.getOperation());
 		}
 		doEvict(cache, key);
 	}

spring-context-support/src/main/java/org/springframework/cache/jcache/interceptor/CacheRemoveOperation.java

 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2019 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -50,8 +50,8 @@ class CacheRemoveOperation extends AbstractJCacheKeyOperation<CacheRemove> {
 	}
 
 	/**
-	 * Specify if the cache entry should be remove before invoking the method. By default, the
-	 * cache entry is removed after the method invocation.
+	 * Specify if the cache entry should be removed before invoking the method.
+	 * <p>By default, the cache entry is removed after the method invocation.
 	 * @see javax.cache.annotation.CacheRemove#afterInvocation()
 	 */
 	public boolean isEarlyRemove() {

spring-context-support/src/main/java/org/springframework/cache/transaction/TransactionAwareCacheDecorator.java

 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2019 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -25,14 +25,16 @@ import org.springframework.transaction.support.TransactionSynchronizationManager
 import org.springframework.util.Assert;
 
 /**
- * Cache decorator which synchronizes its {@link #put}, {@link #evict} and {@link #clear}
- * operations with Spring-managed transactions (through Spring's {@link TransactionSynchronizationManager},
- * performing the actual cache put/evict/clear operation only in the after-commit phase of a
- * successful transaction. If no transaction is active, {@link #put}, {@link #evict} and
+ * Cache decorator which synchronizes its {@link #put}, {@link #evict} and
+ * {@link #clear} operations with Spring-managed transactions (through Spring's
+ * {@link TransactionSynchronizationManager}, performing the actual cache
+ * put/evict/clear operation only in the after-commit phase of a successful
+ * transaction. If no transaction is active, {@link #put}, {@link #evict} and
  * {@link #clear} operations will be performed immediately, as usual.
  *
- * <p>Use of more aggressive operations such as {@link #putIfAbsent} cannot be deferred
- * to the after-commit phase of a running transaction. Use these with care.
+ * <p><b>Note:</b> Use of immediate operations such as {@link #putIfAbsent}
+ * cannot be deferred to the after-commit phase of a running transaction.
+ * Use these with care in a transactional environment.
  *
  * @author Juergen Hoeller
  * @author Stephane Nicoll
@@ -54,6 +56,7 @@ public class TransactionAwareCacheDecorator implements Cache {
 		this.targetCache = targetCache;
 	}
 
+
 	/**
 	 * Return the target Cache that this Cache should delegate to.
 	 */

spring-context/src/main/java/org/springframework/cache/Cache.java

 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2019 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -55,6 +55,7 @@ public interface Cache {
 	 * a cached {@code null} value. A straight {@code null} being
 	 * returned means that the cache contains no mapping for this key.
 	 * @see #get(Object, Class)
+	 * @see #get(Object, Callable)
 	 */
 	@Nullable
 	ValueWrapper get(Object key);
@@ -94,6 +95,7 @@ public interface Cache {
 	 * @return the value to which this cache maps the specified key
 	 * @throws ValueRetrievalException if the {@code valueLoader} throws an exception
 	 * @since 4.3
+	 * @see #get(Object)
 	 */
 	@Nullable
 	<T> T get(Object key, Callable<T> valueLoader);
@@ -112,13 +114,11 @@ public interface Cache {
 	 * if it is not set already.
 	 * <p>This is equivalent to:
 	 * <pre><code>
-	 * Object existingValue = cache.get(key);
+	 * ValueWrapper existingValue = cache.get(key);
 	 * if (existingValue == null) {
 	 *     cache.put(key, value);
-	 *     return null;
-	 * } else {
-	 *     return existingValue;
 	 * }
+	 * return existingValue;
 	 * </code></pre>
 	 * except that the action is performed atomically. While all out-of-the-box
 	 * {@link CacheManager} implementations are able to perform the put atomically,
@@ -132,6 +132,7 @@ public interface Cache {
 	 * mapping for that key prior to this call. Returning {@code null} is therefore
 	 * an indicator that the given {@code value} has been associated with the key.
 	 * @since 4.1
+	 * @see #put(Object, Object)
 	 */
 	@Nullable
 	ValueWrapper putIfAbsent(Object key, @Nullable Object value);
@@ -143,7 +144,7 @@ public interface Cache {
 	void evict(Object key);
 
 	/**
-	 * Remove all mappings from the cache.
+	 * Clear the cache through removing all mappings.
 	 */
 	void clear();
 

spring-context/src/main/java/org/springframework/cache/annotation/CacheEvict.java

@@ -142,7 +142,7 @@ public @interface CacheEvict {
 	 * occur irrespective of the method outcome (i.e., whether it threw an
 	 * exception or not).
 	 * <p>Defaults to {@code false}, meaning that the cache eviction operation
-	 * will occur <em>after</em> the advised method is invoked successfully (i.e.,
+	 * will occur <em>after</em> the advised method is invoked successfully (i.e.
 	 * only if the invocation did not throw an exception).
 	 */
 	boolean beforeInvocation() default false;

spring-context/src/main/java/org/springframework/cache/concurrent/ConcurrentMapCache.java

 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2019 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -141,7 +141,7 @@ public class ConcurrentMapCache extends AbstractValueAdaptingCache {
 	@Override
 	@Nullable
 	public <T> T get(Object key, Callable<T> valueLoader) {
-		return (T) fromStoreValue(this.store.computeIfAbsent(key, r -> {
+		return (T) fromStoreValue(this.store.computeIfAbsent(key, k -> {
 			try {
 				return toStoreValue(valueLoader.call());
 			}