001/*
002 * Copyright 2002-2018 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 org.springframework.cache.CacheManager;
020import org.springframework.cache.interceptor.CacheErrorHandler;
021import org.springframework.cache.interceptor.CacheResolver;
022import org.springframework.cache.interceptor.KeyGenerator;
023
024/**
025 * Interface to be implemented by @{@link org.springframework.context.annotation.Configuration
026 * Configuration} classes annotated with @{@link EnableCaching} that wish or need to
027 * specify explicitly how caches are resolved and how keys are generated for annotation-driven
028 * cache management. Consider extending {@link CachingConfigurerSupport}, which provides a
029 * stub implementation of all interface methods.
030 *
031 * <p>See @{@link EnableCaching} for general examples and context; see
032 * {@link #cacheManager()}, {@link #cacheResolver()} and {@link #keyGenerator()}
033 * for detailed instructions.
034 *
035 * @author Chris Beams
036 * @author Stephane Nicoll
037 * @since 3.1
038 * @see EnableCaching
039 * @see CachingConfigurerSupport
040 */
041public interface CachingConfigurer {
042
043        /**
044         * Return the cache manager bean to use for annotation-driven cache
045         * management. A default {@link CacheResolver} will be initialized
046         * behind the scenes with this cache manager. For more fine-grained
047         * management of the cache resolution, consider setting the
048         * {@link CacheResolver} directly.
049         * <p>Implementations must explicitly declare
050         * {@link org.springframework.context.annotation.Bean @Bean}, e.g.
051         * <pre class="code">
052         * &#064;Configuration
053         * &#064;EnableCaching
054         * public class AppConfig extends CachingConfigurerSupport {
055         *     &#064;Bean // important!
056         *     &#064;Override
057         *     public CacheManager cacheManager() {
058         *         // configure and return CacheManager instance
059         *     }
060         *     // ...
061         * }
062         * </pre>
063         * See @{@link EnableCaching} for more complete examples.
064         */
065        CacheManager cacheManager();
066
067        /**
068         * Return the {@link CacheResolver} bean to use to resolve regular caches for
069         * annotation-driven cache management. This is an alternative and more powerful
070         * option of specifying the {@link CacheManager} to use.
071         * <p>If both a {@link #cacheManager()} and {@code #cacheResolver()} are set,
072         * the cache manager is ignored.
073         * <p>Implementations must explicitly declare
074         * {@link org.springframework.context.annotation.Bean @Bean}, e.g.
075         * <pre class="code">
076         * &#064;Configuration
077         * &#064;EnableCaching
078         * public class AppConfig extends CachingConfigurerSupport {
079         *     &#064;Bean // important!
080         *     &#064;Override
081         *     public CacheResolver cacheResolver() {
082         *         // configure and return CacheResolver instance
083         *     }
084         *     // ...
085         * }
086         * </pre>
087         * See {@link EnableCaching} for more complete examples.
088         */
089        CacheResolver cacheResolver();
090
091        /**
092         * Return the key generator bean to use for annotation-driven cache management.
093         * Implementations must explicitly declare
094         * {@link org.springframework.context.annotation.Bean @Bean}, e.g.
095         * <pre class="code">
096         * &#064;Configuration
097         * &#064;EnableCaching
098         * public class AppConfig extends CachingConfigurerSupport {
099         *     &#064;Bean // important!
100         *     &#064;Override
101         *     public KeyGenerator keyGenerator() {
102         *         // configure and return KeyGenerator instance
103         *     }
104         *     // ...
105         * }
106         * </pre>
107         * See @{@link EnableCaching} for more complete examples.
108         */
109        KeyGenerator keyGenerator();
110
111        /**
112         * Return the {@link CacheErrorHandler} to use to handle cache-related errors.
113         * <p>By default,{@link org.springframework.cache.interceptor.SimpleCacheErrorHandler}
114         * is used and simply throws the exception back at the client.
115         * <p>Implementations must explicitly declare
116         * {@link org.springframework.context.annotation.Bean @Bean}, e.g.
117         * <pre class="code">
118         * &#064;Configuration
119         * &#064;EnableCaching
120         * public class AppConfig extends CachingConfigurerSupport {
121         *     &#064;Bean // important!
122         *     &#064;Override
123         *     public CacheErrorHandler errorHandler() {
124         *         // configure and return CacheErrorHandler instance
125         *     }
126         *     // ...
127         * }
128         * </pre>
129         * See @{@link EnableCaching} for more complete examples.
130         */
131        CacheErrorHandler errorHandler();
132
133}