001/*
002 * Copyright 2002-2016 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.cache.annotation;
018
019import java.lang.annotation.Documented;
020import java.lang.annotation.ElementType;
021import java.lang.annotation.Inherited;
022import java.lang.annotation.Retention;
023import java.lang.annotation.RetentionPolicy;
024import java.lang.annotation.Target;
025
026import org.springframework.core.annotation.AliasFor;
027
028/**
029 * Annotation indicating that a method (or all methods on a class) triggers a
030 * {@link org.springframework.cache.Cache#evict(Object) cache evict} operation.
031 *
032 * <p>This annotation may be used as a <em>meta-annotation</em> to create custom
033 * <em>composed annotations</em> with attribute overrides.
034 *
035 * @author Costin Leau
036 * @author Stephane Nicoll
037 * @author Sam Brannen
038 * @since 3.1
039 * @see CacheConfig
040 */
041@Target({ElementType.METHOD, ElementType.TYPE})
042@Retention(RetentionPolicy.RUNTIME)
043@Inherited
044@Documented
045public @interface CacheEvict {
046
047        /**
048         * Alias for {@link #cacheNames}.
049         */
050        @AliasFor("cacheNames")
051        String[] value() default {};
052
053        /**
054         * Names of the caches to use for the cache eviction operation.
055         * <p>Names may be used to determine the target cache (or caches), matching
056         * the qualifier value or bean name of a specific bean definition.
057         * @since 4.2
058         * @see #value
059         * @see CacheConfig#cacheNames
060         */
061        @AliasFor("value")
062        String[] cacheNames() default {};
063
064        /**
065         * Spring Expression Language (SpEL) expression for computing the key dynamically.
066         * <p>Default is {@code ""}, meaning all method parameters are considered as a key,
067         * unless a custom {@link #keyGenerator} has been set.
068         * <p>The SpEL expression evaluates against a dedicated context that provides the
069         * following meta-data:
070         * <ul>
071         * <li>{@code #result} for a reference to the result of the method invocation, which
072         * can only be used if {@link #beforeInvocation()} is {@code false}. For supported
073         * wrappers such as {@code Optional}, {@code #result} refers to the actual object,
074         * not the wrapper</li>
075         * <li>{@code #root.method}, {@code #root.target}, and {@code #root.caches} for
076         * references to the {@link java.lang.reflect.Method method}, target object, and
077         * affected cache(s) respectively.</li>
078         * <li>Shortcuts for the method name ({@code #root.methodName}) and target class
079         * ({@code #root.targetClass}) are also available.
080         * <li>Method arguments can be accessed by index. For instance the second argument
081         * can be accessed via {@code #root.args[1]}, {@code #p1} or {@code #a1}. Arguments
082         * can also be accessed by name if that information is available.</li>
083         * </ul>
084         */
085        String key() default "";
086
087        /**
088         * The bean name of the custom {@link org.springframework.cache.interceptor.KeyGenerator}
089         * to use.
090         * <p>Mutually exclusive with the {@link #key} attribute.
091         * @see CacheConfig#keyGenerator
092         */
093        String keyGenerator() default "";
094
095        /**
096         * The bean name of the custom {@link org.springframework.cache.CacheManager} to use to
097         * create a default {@link org.springframework.cache.interceptor.CacheResolver} if none
098         * is set already.
099         * <p>Mutually exclusive with the {@link #cacheResolver} attribute.
100         * @see org.springframework.cache.interceptor.SimpleCacheResolver
101         * @see CacheConfig#cacheManager
102         */
103        String cacheManager() default "";
104
105        /**
106         * The bean name of the custom {@link org.springframework.cache.interceptor.CacheResolver}
107         * to use.
108         * @see CacheConfig#cacheResolver
109         */
110        String cacheResolver() default "";
111
112        /**
113         * Spring Expression Language (SpEL) expression used for making the cache
114         * eviction operation conditional.
115         * <p>Default is {@code ""}, meaning the cache eviction is always performed.
116         * <p>The SpEL expression evaluates against a dedicated context that provides the
117         * following meta-data:
118         * <ul>
119         * <li>{@code #root.method}, {@code #root.target}, and {@code #root.caches} for
120         * references to the {@link java.lang.reflect.Method method}, target object, and
121         * affected cache(s) respectively.</li>
122         * <li>Shortcuts for the method name ({@code #root.methodName}) and target class
123         * ({@code #root.targetClass}) are also available.
124         * <li>Method arguments can be accessed by index. For instance the second argument
125         * can be accessed via {@code #root.args[1]}, {@code #p1} or {@code #a1}. Arguments
126         * can also be accessed by name if that information is available.</li>
127         * </ul>
128         */
129        String condition() default "";
130
131        /**
132         * Whether all the entries inside the cache(s) are removed.
133         * <p>By default, only the value under the associated key is removed.
134         * <p>Note that setting this parameter to {@code true} and specifying a
135         * {@link #key} is not allowed.
136         */
137        boolean allEntries() default false;
138
139        /**
140         * Whether the eviction should occur before the method is invoked.
141         * <p>Setting this attribute to {@code true}, causes the eviction to
142         * occur irrespective of the method outcome (i.e., whether it threw an
143         * exception or not).
144         * <p>Defaults to {@code false}, meaning that the cache eviction operation
145         * will occur <em>after</em> the advised method is invoked successfully (i.e.,
146         * only if the invocation did not throw an exception).
147         */
148        boolean beforeInvocation() default false;
149
150}