javax.cache.annotation

Annotation Type CachePut

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

When a method annotated with CachePut is invoked a GeneratedCacheKey will be generated and Cache.put(Object, Object) will be invoked on the specified cache storing the value marked with CacheValue. Null values are cached by default but this behavior can be disabled via the cacheNull() property.

The default behavior is to call Cache.put(Object, Object) after the annotated method is invoked, this behavior can be changed by setting afterInvocation() to false in which case Cache.put(Object, Object) will be called before the annotated method is invoked.

Example of caching the Domain object with a key generated from the String and int parameters. The CacheValue annotation is used to designate which parameter should be stored in the "domainDao" cache.

 package my.app;
 
 public class DomainDao {
   @CachePut(cacheName="domainCache")
   public void updateDomain(String domainId, int index, @CacheValue Domain domain) {
     ...
   }
 }
 

Exception Handling, only used if afterInvocation() is true.

1. If cacheFor() and noCacheFor() are both empty then all exceptions prevent the put
2. If cacheFor() is specified and noCacheFor() is not specified then only exceptions which pass an instanceof check against the cacheFor list result in a put
3. If noCacheFor() is specified and cacheFor() is not specified then all exceptions which do not pass an instanceof check against the noCacheFor result in a put
4. If cacheFor() and noCacheFor() are both specified then exceptions which pass an instanceof check against the cacheFor list but do not pass an instanceof check against the noCacheFor list result in a put

Since:

1.0

Author:

Eric Dalquist, Rick Hightower

See Also:

CacheValue, CacheKey

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
boolean	afterInvocation When Cache.put(Object, Object) should be called.
Class<? extends Throwable>[]	cacheFor Defines zero (0) or more exception classes, which must be a subclass of Throwable, indicating which exception types must cause the parameter to 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 CacheValue values will not be cached.
Class<? extends CacheResolverFactory>	cacheResolverFactory The CacheResolverFactory used to find the CacheResolver to use at runtime.
Class<? extends Throwable>[]	noCacheFor Defines zero (0) or more exception Classes, which must be a subclass of Throwable, indicating which exception types must not cause the parameter to be cached.

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:

""

afterInvocation

public abstract boolean afterInvocation

When Cache.put(Object, Object) should be called. If true it is called after the annotated method invocation completes successfully. If false it is called before the annotated method is invoked.

Defaults to true.

If true and the annotated method throws an exception the rules governing cacheFor() and noCacheFor() will be followed.

Default:

true

cacheNull

public abstract boolean cacheNull

If set to false null CacheValue values will not be cached. If true (the default) null CacheValue 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

cacheFor

public abstract Class<? extends Throwable>[] cacheFor

Defines zero (0) or more exception classes, which must be a subclass of Throwable, indicating which exception types must cause the parameter to be cached. Only used if afterInvocation() is true.

Default:

{}

noCacheFor

public abstract Class<? extends Throwable>[] noCacheFor

Defines zero (0) or more exception Classes, which must be a subclass of Throwable, indicating which exception types must not cause the parameter to be cached. Only used if afterInvocation() is true.

Default:

{}