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#put(Object, Object) cache put} operation.
031 *
032 * <p>In contrast to the {@link Cacheable @Cacheable} annotation, this annotation
033 * does not cause the advised method to be skipped. Rather, it always causes the
034 * method to be invoked and its result to be stored in the associated cache. Note
035 * that Java8's {@code Optional} return types are automatically handled and its
036 * content is stored in the cache if present.
037 *
038 * <p>This annotation may be used as a <em>meta-annotation</em> to create custom
039 * <em>composed annotations</em> with attribute overrides.
040 *
041 * @author Costin Leau
042 * @author Phillip Webb
043 * @author Stephane Nicoll
044 * @author Sam Brannen
045 * @since 3.1
046 * @see CacheConfig
047 */
048@Target({ElementType.METHOD, ElementType.TYPE})
049@Retention(RetentionPolicy.RUNTIME)
050@Inherited
051@Documented
052public @interface CachePut {
053
054        /**
055         * Alias for {@link #cacheNames}.
056         */
057        @AliasFor("cacheNames")
058        String[] value() default {};
059
060        /**
061         * Names of the caches to use for the cache put operation.
062         * <p>Names may be used to determine the target cache (or caches), matching
063         * the qualifier value or bean name of a specific bean definition.
064         * @since 4.2
065         * @see #value
066         * @see CacheConfig#cacheNames
067         */
068        @AliasFor("value")
069        String[] cacheNames() default {};
070
071        /**
072         * Spring Expression Language (SpEL) expression for computing the key dynamically.
073         * <p>Default is {@code ""}, meaning all method parameters are considered as a key,
074         * unless a custom {@link #keyGenerator} has been set.
075         * <p>The SpEL expression evaluates against a dedicated context that provides the
076         * following meta-data:
077         * <ul>
078         * <li>{@code #result} for a reference to the result of the method invocation. For
079         * supported wrappers such as {@code Optional}, {@code #result} refers to the actual
080         * object, not the wrapper</li>
081         * <li>{@code #root.method}, {@code #root.target}, and {@code #root.caches} for
082         * references to the {@link java.lang.reflect.Method method}, target object, and
083         * affected cache(s) respectively.</li>
084         * <li>Shortcuts for the method name ({@code #root.methodName}) and target class
085         * ({@code #root.targetClass}) are also available.
086         * <li>Method arguments can be accessed by index. For instance the second argument
087         * can be accessed via {@code #root.args[1]}, {@code #p1} or {@code #a1}. Arguments
088         * can also be accessed by name if that information is available.</li>
089         * </ul>
090         */
091        String key() default "";
092
093        /**
094         * The bean name of the custom {@link org.springframework.cache.interceptor.KeyGenerator}
095         * to use.
096         * <p>Mutually exclusive with the {@link #key} attribute.
097         * @see CacheConfig#keyGenerator
098         */
099        String keyGenerator() default "";
100
101        /**
102         * The bean name of the custom {@link org.springframework.cache.CacheManager} to use to
103         * create a default {@link org.springframework.cache.interceptor.CacheResolver} if none
104         * is set already.
105         * <p>Mutually exclusive with the {@link #cacheResolver} attribute.
106         * @see org.springframework.cache.interceptor.SimpleCacheResolver
107         * @see CacheConfig#cacheManager
108         */
109        String cacheManager() default "";
110
111        /**
112         * The bean name of the custom {@link org.springframework.cache.interceptor.CacheResolver}
113         * to use.
114         * @see CacheConfig#cacheResolver
115         */
116        String cacheResolver() default "";
117
118        /**
119         * Spring Expression Language (SpEL) expression used for making the cache
120         * put operation conditional.
121         * <p>Default is {@code ""}, meaning the method result is always cached.
122         * <p>The SpEL expression evaluates against a dedicated context that provides the
123         * following meta-data:
124         * <ul>
125         * <li>{@code #root.method}, {@code #root.target}, and {@code #root.caches} for
126         * references to the {@link java.lang.reflect.Method method}, target object, and
127         * affected cache(s) respectively.</li>
128         * <li>Shortcuts for the method name ({@code #root.methodName}) and target class
129         * ({@code #root.targetClass}) are also available.
130         * <li>Method arguments can be accessed by index. For instance the second argument
131         * can be accessed via {@code #root.args[1]}, {@code #p1} or {@code #a1}. Arguments
132         * can also be accessed by name if that information is available.</li>
133         * </ul>
134         */
135        String condition() default "";
136
137        /**
138         * Spring Expression Language (SpEL) expression used to veto the cache put operation.
139         * <p>Unlike {@link #condition}, this expression is evaluated after the method
140         * has been called and can therefore refer to the {@code result}.
141         * <p>Default is {@code ""}, meaning that caching is never vetoed.
142         * <p>The SpEL expression evaluates against a dedicated context that provides the
143         * following meta-data:
144         * <ul>
145         * <li>{@code #result} for a reference to the result of the method invocation. For
146         * supported wrappers such as {@code Optional}, {@code #result} refers to the actual
147         * object, not the wrapper</li>
148         * <li>{@code #root.method}, {@code #root.target}, and {@code #root.caches} for
149         * references to the {@link java.lang.reflect.Method method}, target object, and
150         * affected cache(s) respectively.</li>
151         * <li>Shortcuts for the method name ({@code #root.methodName}) and target class
152         * ({@code #root.targetClass}) are also available.
153         * <li>Method arguments can be accessed by index. For instance the second argument
154         * can be accessed via {@code #root.args[1]}, {@code #p1} or {@code #a1}. Arguments
155         * can also be accessed by name if that information is available.</li>
156         * </ul>
157         * @since 3.2
158         */
159        String unless() default "";
160
161}