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}