javax.cache.annotation

Annotation Type CacheResult

@Target(value={METHOD,TYPE})
@Retention(value=RUNTIME)
public @interface CacheResult

When a method annotated with CacheResult is invoked a GeneratedCacheKey will be generated and 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.

null return values are cached by default, this behavior can be disabled by setting the cacheNull() property to false.

Exceptions are not cached by default. Caching of exceptions can be enabled by specifying an 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 cachedExceptions() and nonCachedExceptions() properties can be used to control which exceptions are cached and which are not.

To always invoke the annotated method and still cache the result set skipGet() to true. This will disable the pre-invocation Cache.get(Object) call. If exceptionCacheName() is specifid 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 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 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 exceptionCacheName() the following rules are used to determine if a thrown exception is cached:

1. If cachedExceptions() and nonCachedExceptions() are both empty then all exceptions are cached
2. If cachedExceptions() is specified and nonCachedExceptions() is not specified then only exceptions which pass an instanceof check against the cachedExceptions list are cached
3. If nonCachedExceptions() is specified and cachedExceptions() is not specified then all exceptions which do not pass an instanceof check against the nonCachedExceptions list are cached
4. If cachedExceptions() and nonCachedExceptions() are both specified then exceptions which pass an instanceof check against the cachedExceptions list but do not pass an instanceof check against the nonCachedExceptions list are cached

Since:

1.0

Author:

Eric Dalquist, Rick Hightower

See Also:

CacheKey

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
Class<? extends Throwable>[]	cachedExceptions Defines zero (0) or more exception classes, which must be a subclass of Throwable, indicating which exception types which must be cached.
Class<? extends CacheKeyGenerator>	cacheKeyGenerator The CacheKeyGenerator to use to generate the GeneratedCacheKey for interacting with the specified Cache.
String	cacheName The name of the cache.
boolean	cacheNull If set to false null return values will not be cached.
Class<? extends CacheResolverFactory>	cacheResolverFactory The CacheResolverFactory used to find the CacheResolver to use at runtime.
String	exceptionCacheName The name of the cache to cache exceptions.
Class<? extends Throwable>[]	nonCachedExceptions Defines zero (0) or more exception Classes, which must be a subclass of Throwable, indicating which exception types must not be cached.
boolean	skipGet If set to true the pre-invocation Cache.get(Object) is skipped and the annotated method is always executed with the returned value being cached as normal.

Element Detail

cacheName

public abstract String cacheName

The name of the cache.

If not specified defaults first to CacheDefaults.cacheName() an if that is not set it defaults to: package.name.ClassName.methodName(package.ParameterType,package.ParameterType)

Default:

""

skipGet

public abstract boolean skipGet

If set to true the pre-invocation 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 which should always be executed and have their returned value placed in the cache.

If true and an 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 Also:

CachePut

Default:

false

cacheNull

public abstract boolean cacheNull

If set to false null return values will not be cached. If true (the default) null return values will be cached.

Defaults to true

Default:

true

cacheResolverFactory

public abstract Class<? extends CacheResolverFactory> cacheResolverFactory

The CacheResolverFactory used to find the CacheResolver to use at runtime.

The default resolver pair will resolve the cache by name from the default CacheManager

Default:

javax.cache.annotation.CacheResolverFactory.class

cacheKeyGenerator

public abstract Class<? extends CacheKeyGenerator> cacheKeyGenerator

The CacheKeyGenerator to use to generate the GeneratedCacheKey for interacting with the specified Cache.

Defaults to a key generator that uses Arrays.deepHashCode(Object[]) and Arrays.deepEquals(Object[], Object[]) with the array returned by CacheKeyInvocationContext.getKeyParameters()

See Also:

CacheKey

Default:

javax.cache.annotation.CacheKeyGenerator.class

exceptionCacheName

public abstract String exceptionCacheName

The name of the cache to cache exceptions.

If not specified no exception caching is done.

Default:

""

cachedExceptions

public abstract Class<? extends Throwable>[] cachedExceptions

Defines zero (0) or more exception classes, which must be a subclass of Throwable, indicating which exception types which must be cached. Only consulted if exceptionCacheName() is specified.

Default:

{}

nonCachedExceptions

public abstract Class<? extends Throwable>[] nonCachedExceptions

Defines zero (0) or more exception Classes, which must be a subclass of Throwable, indicating which exception types must not be cached. Only consulted if exceptionCacheName() is specified.

Default:

{}