From f7492348ba5c4ac39005565f356d64b79026dd2d Mon Sep 17 00:00:00 2001 From: Stephane Nicoll Date: Wed, 9 Dec 2015 11:24:53 +0100 Subject: [PATCH] Polish cache javadoc Issue: SPR-13746 (cherry picked from commit 34b596c) --- .../cache/annotation/CacheEvict.java | 82 +++++++++++----- .../cache/annotation/CachePut.java | 94 +++++++++++++----- .../cache/annotation/Cacheable.java | 98 ++++++++++++++----- src/asciidoc/index.adoc | 6 +- 4 files changed, 205 insertions(+), 75 deletions(-) diff --git a/spring-context/src/main/java/org/springframework/cache/annotation/CacheEvict.java b/spring-context/src/main/java/org/springframework/cache/annotation/CacheEvict.java index fcc3e443908..9aacb378f9a 100644 --- a/spring-context/src/main/java/org/springframework/cache/annotation/CacheEvict.java +++ b/spring-context/src/main/java/org/springframework/cache/annotation/CacheEvict.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2014 the original author or authors. + * Copyright 2002-2015 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. @@ -24,8 +24,8 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Annotation indicating that a method (or all methods on a class) trigger(s) - * a cache invalidate operation. + * Annotation indicating that a method (or all methods on a class) triggers a + * {@link org.springframework.cache.Cache#evict(Object) cache evict} operation. * * @author Costin Leau * @author Stephane Nicoll @@ -39,22 +39,39 @@ import java.lang.annotation.Target; public @interface CacheEvict { /** - * Qualifier value for the specified cached operation. - *

May be used to determine the target cache (or caches), matching the qualifier - * value (or the bean name(s)) of (a) specific bean definition. + * Names of the caches to use for the cache eviction operation. + *

Names may be used to determine the target cache (or caches), matching + * the qualifier value or bean name of a specific bean definition. + * @see CacheConfig#cacheNames */ String[] value() default {}; /** - * Spring Expression Language (SpEL) attribute for computing the key dynamically. - *

Default is "", meaning all method parameters are considered as a key, unless - * a custom {@link #keyGenerator()} has been set. + * Spring Expression Language (SpEL) expression for computing the key dynamically. + *

Default is {@code ""}, meaning all method parameters are considered as a key, + * unless a custom {@link #keyGenerator} has been set. + *

The SpEL expression evaluates again a dedicated context that provides the + * following meta-data: + *

*/ String key() default ""; /** - * The bean name of the custom {@link org.springframework.cache.interceptor.KeyGenerator} to use. - *

Mutually exclusive with the {@link #key()} attribute. + * The bean name of the custom {@link org.springframework.cache.interceptor.KeyGenerator} + * to use. + *

Mutually exclusive with the {@link #key} attribute. + * @see CacheConfig#keyGenerator */ String keyGenerator() default ""; @@ -62,34 +79,55 @@ public @interface CacheEvict { * The bean name of the custom {@link org.springframework.cache.CacheManager} to use to * create a default {@link org.springframework.cache.interceptor.CacheResolver} if none * is set already. - *

Mutually exclusive with the {@link #cacheResolver()} attribute. + *

Mutually exclusive with the {@link #cacheResolver} attribute. * @see org.springframework.cache.interceptor.SimpleCacheResolver + * @see CacheConfig#cacheManager */ String cacheManager() default ""; /** - * The bean name of the custom {@link org.springframework.cache.interceptor.CacheResolver} to use. + * The bean name of the custom {@link org.springframework.cache.interceptor.CacheResolver} + * to use. + * @see CacheConfig#cacheResolver */ String cacheResolver() default ""; /** - * Spring Expression Language (SpEL) attribute used for conditioning the method caching. - *

Default is "", meaning the method is always cached. + * Spring Expression Language (SpEL) expression used for making the cache + * eviction operation conditional. + *

Default is {@code ""}, meaning the cache eviction is always performed. + *

The SpEL expression evaluates again a dedicated context that provides the + * following meta-data: + *

*/ String condition() default ""; /** - * Whether or not all the entries inside the cache(s) are removed or not. By - * default, only the value under the associated key is removed. - *

Note that setting this parameter to {@code true} and specifying a {@link #key()} - * is not allowed. + * Whether all the entries inside the cache(s) are removed. + *

By default, only the value under the associated key is removed. + *

Note that setting this parameter to {@code true} and specifying a + * {@link #key} is not allowed. */ boolean allEntries() default false; /** - * Whether the eviction should occur after the method is successfully invoked (default) - * or before. The latter causes the eviction to occur irrespective of the method outcome (whether - * it threw an exception or not) while the former does not. + * Whether the eviction should occur before the method is invoked. + *

Setting this attribute to {@code true}, causes the eviction to + * occur irrespective of the method outcome (i.e., whether it threw an + * exception or not). + *

Defaults to {@code false}, meaning that the cache eviction operation + * will occur after the advised method is invoked successfully (i.e., + * only if the invocation did not throw an exception). */ boolean beforeInvocation() default false; + } diff --git a/spring-context/src/main/java/org/springframework/cache/annotation/CachePut.java b/spring-context/src/main/java/org/springframework/cache/annotation/CachePut.java index 13b94c4f8f2..1c1f5d57bc4 100644 --- a/spring-context/src/main/java/org/springframework/cache/annotation/CachePut.java +++ b/spring-context/src/main/java/org/springframework/cache/annotation/CachePut.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2014 the original author or authors. + * Copyright 2002-2015 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. @@ -23,13 +23,13 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; -import org.springframework.cache.Cache; - /** - * Annotation indicating that a method (or all methods on a class) trigger(s) - * a {@link Cache#put(Object, Object)} operation. As opposed to {@link Cacheable} annotation, - * this annotation does not cause the target method to be skipped - rather it - * always causes the method to be invoked and its result to be placed into the cache. + * Annotation indicating that a method (or all methods on a class) triggers a + * {@link org.springframework.cache.Cache#put(Object, Object) cache put} operation. + * + *

In contrast to the {@link Cacheable @Cacheable} annotation, this annotation + * does not cause the advised method to be skipped. Rather, it always causes the + * method to be invoked and its result to be stored in the associated cache. * * @author Costin Leau * @author Phillip Webb @@ -37,29 +37,45 @@ import org.springframework.cache.Cache; * @since 3.1 * @see CacheConfig */ -@Target({ ElementType.METHOD, ElementType.TYPE }) +@Target({ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) @Inherited @Documented public @interface CachePut { /** - * Name of the caches in which the update takes place. - *

May be used to determine the target cache (or caches), matching the - * qualifier value (or the bean name(s)) of (a) specific bean definition. + * Names of the caches to use for the cache put operation. + *

Names may be used to determine the target cache (or caches), matching + * the qualifier value or bean name of a specific bean definition. + * @see CacheConfig#cacheNames */ String[] value() default {}; /** - * Spring Expression Language (SpEL) attribute for computing the key dynamically. - *

Default is "", meaning all method parameters are considered as a key, unless - * a custom {@link #keyGenerator()} has been set. + * Spring Expression Language (SpEL) expression for computing the key dynamically. + *

Default is {@code ""}, meaning all method parameters are considered as a key, + * unless a custom {@link #keyGenerator} has been set. + *

The SpEL expression evaluates again a dedicated context that provides the + * following meta-data: + *

*/ String key() default ""; /** - * The bean name of the custom {@link org.springframework.cache.interceptor.KeyGenerator} to use. - *

Mutually exclusive with the {@link #key()} attribute. + * The bean name of the custom {@link org.springframework.cache.interceptor.KeyGenerator} + * to use. + *

Mutually exclusive with the {@link #key} attribute. + * @see CacheConfig#keyGenerator */ String keyGenerator() default ""; @@ -67,28 +83,58 @@ public @interface CachePut { * The bean name of the custom {@link org.springframework.cache.CacheManager} to use to * create a default {@link org.springframework.cache.interceptor.CacheResolver} if none * is set already. - *

Mutually exclusive with the {@link #cacheResolver()} attribute. + *

Mutually exclusive with the {@link #cacheResolver} attribute. * @see org.springframework.cache.interceptor.SimpleCacheResolver + * @see CacheConfig#cacheManager */ String cacheManager() default ""; /** - * The bean name of the custom {@link org.springframework.cache.interceptor.CacheResolver} to use. + * The bean name of the custom {@link org.springframework.cache.interceptor.CacheResolver} + * to use. + * @see CacheConfig#cacheResolver */ String cacheResolver() default ""; /** - * Spring Expression Language (SpEL) attribute used for conditioning the cache update. - *

Default is "", meaning the method result is always cached. + * Spring Expression Language (SpEL) expression used for making the cache + * put operation conditional. + *

Default is {@code ""}, meaning the method result is always cached. + *

The SpEL expression evaluates again a dedicated context that provides the + * following meta-data: + *

*/ String condition() default ""; /** - * Spring Expression Language (SpEL) attribute used to veto the cache update. - *

Unlike {@link #condition()}, this expression is evaluated after the method - * has been called and can therefore refer to the {@code result}. Default is "", - * meaning that caching is never vetoed. + * Spring Expression Language (SpEL) expression used to veto the cache put operation. + *

Unlike {@link #condition}, this expression is evaluated after the method + * has been called and can therefore refer to the {@code result}. + *

Default is {@code ""}, meaning that caching is never vetoed. + *

The SpEL expression evaluates again a dedicated context that provides the + * following meta-data: + *

* @since 3.2 */ String unless() default ""; + } diff --git a/spring-context/src/main/java/org/springframework/cache/annotation/Cacheable.java b/spring-context/src/main/java/org/springframework/cache/annotation/Cacheable.java index 90b93eea362..cff653b3d02 100644 --- a/spring-context/src/main/java/org/springframework/cache/annotation/Cacheable.java +++ b/spring-context/src/main/java/org/springframework/cache/annotation/Cacheable.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2014 the original author or authors. + * Copyright 2002-2015 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. @@ -24,17 +24,18 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Annotation indicating that a method (or all the methods on a class) can be cached. + * Annotation indicating that the result of invoking a method (or all methods + * in a class) can be cached. * - *

Each time a targeted method is invoked, a caching behavior will be applied, - * checking whether the method has been already executed for the given arguments. A - * sensible default simply uses the method parameters to compute the key but a SpEL - * expression can be provided ({@link #key()}) or a custom - * {@link org.springframework.cache.interceptor.KeyGenerator KeyGenerator} implementation - * can replace the default one ({@link #keyGenerator()}). + *

Each time an advised method is invoked, caching behavior will be applied, + * checking whether the method has been already invoked for the given arguments. + * A sensible default simply uses the method parameters to compute the key, but + * a SpEL expression can be provided via the {@link #key} attribute, or a custom + * {@link org.springframework.cache.interceptor.KeyGenerator} implementation can + * replace the default one (see {@link #keyGenerator}). * - *

If no value is found in the cache for the computed key, the method is executed - * and the returned instance is used as the cache value. + *

If no value is found in the cache for the computed key, the target method + * will be invoked and the returned value stored in the associated cache. * * @author Costin Leau * @author Phillip Webb @@ -49,22 +50,37 @@ import java.lang.annotation.Target; public @interface Cacheable { /** - * Name of the caches in which the update takes place. - *

May be used to determine the target cache (or caches), matching the - * qualifier value (or the bean name(s)) of (a) specific bean definition. + * Names of the caches in which method invocation results are stored. + *

Names may be used to determine the target cache (or caches), matching + * the qualifier value or bean name of a specific bean definition. + * @see CacheConfig#cacheNames */ String[] value() default {}; /** - * Spring Expression Language (SpEL) attribute for computing the key dynamically. - *

Default is "", meaning all method parameters are considered as a key, unless - * a custom {@link #keyGenerator()} has been set. + * Spring Expression Language (SpEL) expression for computing the key dynamically. + *

Default is {@code ""}, meaning all method parameters are considered as a key, + * unless a custom {@link #keyGenerator} has been configured. + *

The SpEL expression evaluates again a dedicated context that provides the + * following meta-data: + *

*/ String key() default ""; /** - * The bean name of the custom {@link org.springframework.cache.interceptor.KeyGenerator} to use. - *

Mutually exclusive with the {@link #key()} attribute. + * The bean name of the custom {@link org.springframework.cache.interceptor.KeyGenerator} + * to use. + *

Mutually exclusive with the {@link #key} attribute. + * @see CacheConfig#keyGenerator */ String keyGenerator() default ""; @@ -72,28 +88,58 @@ public @interface Cacheable { * The bean name of the custom {@link org.springframework.cache.CacheManager} to use to * create a default {@link org.springframework.cache.interceptor.CacheResolver} if none * is set already. - *

Mutually exclusive with the {@link #cacheResolver()} attribute. + *

Mutually exclusive with the {@link #cacheResolver} attribute. * @see org.springframework.cache.interceptor.SimpleCacheResolver + * @see CacheConfig#cacheManager */ String cacheManager() default ""; /** - * The bean name of the custom {@link org.springframework.cache.interceptor.CacheResolver} to use. + * The bean name of the custom {@link org.springframework.cache.interceptor.CacheResolver} + * to use. + * @see CacheConfig#cacheResolver */ String cacheResolver() default ""; /** - * Spring Expression Language (SpEL) attribute used for conditioning the method caching. - *

Default is "", meaning the method is always cached. + * Spring Expression Language (SpEL) expression used for making the method + * caching conditional. + *

Default is {@code ""}, meaning the method result is always cached. + *

The SpEL expression evaluates again a dedicated context that provides the + * following meta-data: + *

*/ String condition() default ""; /** - * Spring Expression Language (SpEL) attribute used to veto method caching. - *

Unlike {@link #condition()}, this expression is evaluated after the method - * has been called and can therefore refer to the {@code result}. Default is "", - * meaning that caching is never vetoed. + * Spring Expression Language (SpEL) expression used to veto method caching. + *

Unlike {@link #condition}, this expression is evaluated after the method + * has been called and can therefore refer to the {@code result}. + *

Default is {@code ""}, meaning that caching is never vetoed. + *

The SpEL expression evaluates again a dedicated context that provides the + * following meta-data: + *

* @since 3.2 */ String unless() default ""; + } diff --git a/src/asciidoc/index.adoc b/src/asciidoc/index.adoc index c18bf4e0486..4bd39d5105b 100644 --- a/src/asciidoc/index.adoc +++ b/src/asciidoc/index.adoc @@ -49634,10 +49634,10 @@ conditional computations: | __argument name__ | evaluation context -| Name of any of the method argument. If for some reason the names are not available - (ex: no debug information), the argument names are also available under the `a<#arg>` +| Name of any of the method arguments. If for some reason the names are not available + (e.g. no debug information), the argument names are also available under the `#a<#arg>` where __#arg__ stands for the argument index (starting from 0). -| `iban` or `a0` (one can also use `p0` or `p<#arg>` notation as an alias). +| `#iban` or `#a0` (one can also use `#p0` or `#p<#arg>` notation as an alias). | result | evaluation context