All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.cache.annotation.CacheResult Maven / Gradle / Ivy

Go to download

Easy Redis Java client and Real-Time Data Platform. Valkey compatible. Sync/Async/RxJava3/Reactive API. Client side caching. Over 50 Redis based Java objects and services: JCache API, Apache Tomcat, Hibernate, Spring, Set, Multimap, SortedSet, Map, List, Queue, Deque, Semaphore, Lock, AtomicLong, Map Reduce, Bloom filter, Scheduler, RPC

There is a newer version: 3.40.2
Show newest version
/**
 * Copyright 2011-2016 Terracotta, Inc.
 * Copyright 2011-2016 Oracle America Incorporated
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package javax.cache.annotation;

import javax.cache.Cache;
import javax.cache.CacheManager;
import javax.enterprise.util.Nonbinding;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;


/**
 * When a method annotated with {@link CacheResult} is invoked a
 * {@link GeneratedCacheKey} will be generated and {@link Cache#get(Object)} is
 * called before the annotated method actually executes. If a value is found in the
 * cache it is returned and the annotated method is never actually executed. If no
 * value is found the annotated method is invoked and the returned value is stored
 * in the cache with the generated key.
 * 

* Exceptions are not cached by default. Caching of exceptions can be enabled by * specifying an {@link #exceptionCacheName()}. If an exception cache is specified * it is checked before invoking the annotated method and if a cached exception is * found it is re-thrown. *

* The {@link #cachedExceptions()} and {@link #nonCachedExceptions()} properties * can be used to control the exceptions are cached and those that are not. *

* To always invoke the annotated method and still cache the result set * {@link #skipGet()} to true. This will disable the pre-invocation * {@link Cache#get(Object)} call. If {@link #exceptionCacheName()} is * specified the pre-invocation exception check is also disabled. This feature is * useful for methods that create or update objects to be cached. *

* Example of caching the Domain object with a key generated from the * String and int parameters. *

* With no {@link #cacheName()} specified a cache name of * "my.app.DomainDao.getDomain(java.lang.String,int)" will be generated. *

*

 * package my.app;
 * 
 * public class DomainDao {
 *   @CacheResult
 *   public Domain getDomain(String domainId, int index) {
 *     ...
 *   }
 * }
 * 
*

* Example using the {@link GeneratedCacheKey} annotation so that only the domainId * parameter is used in key generation: *


 * package my.app;
 * 
 * public class DomainDao {
 *   @CacheResult
 *   public Domain getDomain(@CacheKey String domainId, Monitor mon) {
 *     ...
 *   }
 * }
 * 
*

* If exception caching is enabled via specification of * {@link #exceptionCacheName()} the following rules are used to determine if a * thrown exception is cached: *

    *
  1. If {@link #cachedExceptions()} and {@link #nonCachedExceptions()} are both * empty then all exceptions are cached
  2. *
  3. If {@link #cachedExceptions()} is specified and * {@link #nonCachedExceptions()} is not specified then only exceptions * that pass an instanceof check against the cachedExceptions list are cached
  4. *
  5. If {@link #nonCachedExceptions()} is specified and * {@link #cachedExceptions()} is not specified then all exceptions * that do not pass an instanceof check against the nonCachedExceptions list are * cached
  6. *
  7. If {@link #cachedExceptions()} and {@link #nonCachedExceptions()} are both * specified then exceptions that pass an instanceof check against the * cachedExceptions list but do not pass an instanceof check against the * nonCachedExceptions list are cached
  8. *
* * @author Eric Dalquist * @author Rick Hightower * @see CacheKey * @since 1.0 */ @Target({ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) public @interface CacheResult { /** *

* The name of the cache. *

* If not specified defaults first to {@link CacheDefaults#cacheName()} and if * that is not set it defaults to: * package.name.ClassName.methodName(package.ParameterType,package.ParameterType) */ @Nonbinding String cacheName() default ""; /** * If set to true the pre-invocation {@link Cache#get(Object)} is * skipped and the annotated method is always executed with the returned value * being cached as normal. This is useful for create or update methods that * should always be executed and have their returned value placed in the cache. *

* If true and an {@link #exceptionCacheName()} is specified the pre-invocation * check for a thrown exception is also skipped. If an exception is thrown during * invocation it will be cached following the standard exception caching rules. *

* Defaults to false. * * @see CachePut */ @Nonbinding boolean skipGet() default false; /** * The {@link CacheResolverFactory} used to find the {@link CacheResolver} to * use at runtime. *

* The default resolver pair will resolve the cache by name from the default * {@link CacheManager} */ @Nonbinding Class cacheResolverFactory() default CacheResolverFactory.class; /** * The {@link CacheKeyGenerator} to use to generate the {@link GeneratedCacheKey} * for interacting with the specified Cache. *

* Defaults to a key generator that uses * {@link java.util.Arrays#deepHashCode(Object[])} and * {@link java.util.Arrays#deepEquals(Object[], Object[])} with the array * returned by {@link CacheKeyInvocationContext#getKeyParameters()} * * @see CacheKey */ @Nonbinding Class cacheKeyGenerator() default CacheKeyGenerator.class; /** * The name of the cache to cache exceptions. *

* If not specified no exception caching is done. */ @Nonbinding String exceptionCacheName() default ""; /** * Defines zero (0) or more exception {@link Class classes}, that must be a * subclass of {@link Throwable}, indicating the exception types that * must be cached. Only consulted if {@link #exceptionCacheName()} is * specified. */ @Nonbinding Class[] cachedExceptions() default {}; /** * Defines zero (0) or more exception {@link Class Classes}, that must be a * subclass of {@link Throwable}, indicating the exception types that * must not be cached. Only consulted if {@link #exceptionCacheName()} * is specified. */ @Nonbinding Class[] nonCachedExceptions() default {}; }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy