* Like {@link Map}s, {@link Cache}s *
* Unlike {@link Map}s, {@link Cache}s *
null
* will result in a {@link NullPointerException}* A simple example of how to use a cache is: *
* String cacheName = "sampleCache";
* CachingProvider provider = Caching.getCachingProvider();
* CacheManager manager = provider.getCacheManager();
* Cache<Integer, Date> cache = manager.getCache(cacheName, Integer.class,
* Date.class);
* Date value1 = new Date();
* Integer key = 1;
* cache.put(key, value1);
* Date value2 = cache.get(key);
* * If the cache is configured to use read-through, and get would return null * because the entry is missing from the cache, the Cache's {@link CacheLoader} * is called in an attempt to load the entry. * * @param key the key whose associated value is to be returned * @return the element, or null, if it does not exist. * @throws IllegalStateException if the cache is {@link #isClosed()} * @throws NullPointerException if the key is null * @throws CacheException if there is a problem fetching the value * @throws ClassCastException if the implementation is configured to perform * runtime-type-checking, and the key or value * types are incompatible with those that have been * configured for the {@link Cache} */ V get(K key); /** * Gets a collection of entries from the {@link Cache}, returning them as * {@link Map} of the values associated with the set of keys requested. *
* If the cache is configured read-through, and a get for a key would
* return null because an entry is missing from the cache, the Cache's
* {@link CacheLoader} is called in an attempt to load the entry. If an
* entry cannot be loaded for a given key, the key will not be present in
* the returned Map.
*
* @param keys The keys whose associated values are to be returned.
* @return A map of entries that were found for the given keys. Keys not found
* in the cache are not in the returned map.
* @throws NullPointerException if keys is null or if keys contains a null
* @throws IllegalStateException if the cache is {@link #isClosed()}
* @throws CacheException if there is a problem fetching the values
* @throws ClassCastException if the implementation is configured to perform
* runtime-type-checking, and the key or value
* types are incompatible with those that have been
* configured for the {@link Cache}
*/
Map
* More formally, returns true if and only if this cache contains a
* mapping for a key k such that key.equals(k).
* (There can be at most one such mapping.)
* If the cache is configured read-through the associated {@link CacheLoader}
* is not called. Only the cache is checked.
*
* If an entry for a key already exists in the Cache, a value will be loaded
* if and only if
* Implementations may choose to load multiple keys from the provided
* {@link Set} in parallel. Iteration however must not occur in parallel,
* thus allow for non-thread-safe {@link Set}s to be used.
*
* The thread on which the completion listener is called is implementation
* dependent. An implementation may also choose to serialize calls to
* different CompletionListeners rather than use a thread per
* CompletionListener.
*
* @param keys the keys to load
* @param replaceExistingValues when true existing values in the Cache will
* be replaced by those loaded from a CacheLoader
* @param completionListener the CompletionListener (may be null)
* @throws NullPointerException if keys is null or if keys contains a null.
* @throws IllegalStateException if the cache is {@link #isClosed()}
* @throws CacheException thrown if there is a problem performing the
* load. This may also be thrown on calling if
* there are insufficient threads available to
* perform the load.
* @throws ClassCastException if the implementation is configured to perform
* runtime-type-checking, and the key or value
* types are incompatible with those that have been
* configured for the {@link Cache}
*/
void loadAll(Set keys, boolean replaceExistingValues,
CompletionListener completionListener);
/**
* Associates the specified value with the specified key in the cache.
*
* If the {@link Cache} previously contained a mapping for the key, the old
* value is replaced by the specified value. (A cache c is said to
* contain a mapping for a key k if and only if {@link
* #containsKey(Object) c.containsKey(k)} would return true.)
*
* If the cache is configured write-through the
* {@link CacheWriter#write(Cache.Entry)} method will be called.
*
* If the cache previously contained a mapping for
* the key, the old value is replaced by the specified value. (A cache
* c is said to contain a mapping for a key k if and only
* if {@link #containsKey(Object) c.containsKey(k)} would return
* true.)
*
* The previous value is returned, or null if there was no value associated
* with the key previously.
* If the cache is configured write-through the associated
* {@link CacheWriter#write(Cache.Entry)} method will be called.
*
* The effect of this call is equivalent to that of calling
* {@link #put(Object, Object) put(k, v)} on this cache once for each mapping
* from key k to value v in the specified map.
*
* The order in which the individual puts occur is undefined.
*
* The behavior of this operation is undefined if entries in the cache
* corresponding to entries in the map are modified or removed while this
* operation is in progress. or if map is modified while the operation is in
* progress.
*
* In Default Consistency mode, individual puts occur atomically but not
* the entire putAll. Listeners may observe individual updates.
*
* If the cache is configured write-through the associated
* {@link CacheWriter#writeAll} method will be called.
*
* This is equivalent to:
*
* If the cache is configured write-through, and this method returns true,
* the associated {@link CacheWriter#write(Cache.Entry)} method will be called.
*
* More formally, if this cache contains a mapping from key k to
* value v such that
* Returns true if this cache previously associated the key,
* or false if the cache contained no mapping for the key.
*
* The cache will not contain a mapping for the specified key once the
* call returns.
*
* If the cache is configured write-through the associated
* {@link CacheWriter#delete(Object)} method will be called.
*
* This is equivalent to:
*
* If the cache is configured write-through, and this method returns true,
* the associated {@link CacheWriter#delete(Object)} method will be called.
*
* This is equivalent to:
*
* If the cache is configured write-through the associated
* {@link CacheWriter#delete(Object)} method will be called.
*
* This is equivalent to:
*
* If the cache is configured write-through, and this method returns true,
* the associated {@link CacheWriter#write(Cache.Entry)} method will be called.
*
* This is equivalent to
*
* If the cache is configured write-through, and this method returns true,
* the associated {@link CacheWriter#write(Cache.Entry)} method will be called.
*
* This is equivalent to
*
* If the cache is configured write-through, and this method returns true,
* the associated {@link CacheWriter#write(Cache.Entry)} method will be called.
*
* The order in which the individual entries are removed is undefined.
*
* For every entry in the key set, the following are called:
*
* The order that the individual entries are removed is undefined.
*
* For every mapping that exists the following are called:
*
* This is potentially an expensive operation as listeners are invoked.
* Use {@link #clear()} to avoid this.
*
* @throws IllegalStateException if the cache is {@link #isClosed()}
* @throws CacheException if there is a problem during the remove
* @see #clear()
* @see CacheWriter#deleteAll
*/
void removeAll();
/**
* Clears the contents of the cache, without notifying listeners or
* {@link CacheWriter}s.
*
* @throws IllegalStateException if the cache is {@link #isClosed()}
* @throws CacheException if there is a problem during the clear
*/
void clear();
/**
* Provides a standard way to access the configuration of a cache using
* JCache configuration or additional proprietary configuration.
*
* The returned value must be immutable.
*
* If the provider's implementation does not support the specified class,
* the {@link IllegalArgumentException} is thrown.
*
* @param
* The order that the entries for the keys are processed is undefined.
* Implementations may choose to process the entries in any order, including
* concurrently. Furthermore there is no guarantee implementations will
* use the same {@link EntryProcessor} instance to process each entry, as
* the case may be in a non-local cache topology.
*
* The result of executing the {@link EntryProcessor} is returned as a
* {@link Map} of {@link EntryProcessorResult}s, one result per key. Should the
* {@link EntryProcessor} or Caching implementation throw an exception, the
* exception is wrapped and re-thrown when a call to
* {@link javax.cache.processor.EntryProcessorResult#get()} is made.
*
* @param
* Closing a Cache does not necessarily destroy the contents of a Cache.
* It simply signals to the owning CacheManager that the Cache is no longer
* required by the application and that future uses of a specific Cache instance
* should not be permitted.
*
* Depending on the implementation and Cache topology,
* (e.g. a storage-backed or distributed cache), the contents of a closed Cache
* may still be available and accessible by other applications, or, in fact, via
* the Cache Manager that previously owned the Cache, if an application calls
* getCache at some point in the future.
*
* @throws SecurityException when the operation could not be performed
* due to the current security settings
*/
void close();
/**
* Determines whether this Cache instance has been closed. A Cache is
* considered closed if;
*
* This method generally cannot be called to determine whether a Cache instance
* is valid or invalid. A typical client can determine that a Cache is invalid
* by catching any exceptions that might be thrown when an operation is
* attempted.
*
* @return true if this Cache instance is closed; false if it is still open
*/
boolean isClosed();
/**
* Provides a standard way to access the underlying concrete caching
* implementation to provide access to further, proprietary features.
*
* If the provider's implementation does not support the specified class,
* the {@link IllegalArgumentException} is thrown.
*
* @param
* Both listeners registered at configuration time,
* and those created at runtime with {@link #registerCacheEntryListener} can
* be deregistered.
*
* @param cacheEntryListenerConfiguration
* the factory and related configuration
* that was used to create the
* listener
* @throws IllegalStateException if the cache is {@link #isClosed()}
*/
void deregisterCacheEntryListener(CacheEntryListenerConfiguration
* The ordering of iteration over entries is undefined.
*
* During iteration, any entries that are removed will have their appropriate
* CacheEntryRemovedListeners notified.
*
* When iterating over a cache it must be assumed that the underlying
* cache may be changing, with entries being added, removed, evicted
* and expiring. {@link java.util.Iterator#next()} may therefore return
* null.
*
* @throws IllegalStateException if the cache is {@link #isClosed()}
*/
Iterator
* If the provider's implementation does not support the specified class,
* the {@link IllegalArgumentException} is thrown.
*
* @param
* This is the base class for all cache exceptions.
*
* @author Greg Luck
* @since 1.0
*/
public class CacheException extends RuntimeException {
private static final long serialVersionUID = 1L;
/**
* Constructs a new CacheException.
*
* @since 1.0
*/
public CacheException() {
super();
}
/**
* Constructs a new CacheException with a message string.
*
* @param message the detail message. The detail message is saved for
* later retrieval by the {@link #getMessage()} method.
* @since 1.0
*/
public CacheException(String message) {
super(message);
}
/**
* Constructs a CacheException with a message string, and
* a base exception
*
* @param message the detail message. The detail message is saved for
* later retrieval by the {@link #getMessage()} method.
* @param cause the cause (that is saved for later retrieval by the
* {@link #getCause()} method). (A null value is
* permitted, and indicates that the cause is nonexistent or
* unknown.)
* @since 1.0
*/
public CacheException(String message, Throwable cause) {
super(message, cause);
}
/**
* Constructs a new CacheException with the specified cause and a
* detail message of (cause==null ? null : cause.toString())
* (that typically contains the class and detail message of
* cause). This constructor is useful for runtime exceptions
* that are little more than wrappers for other throwables.
*
* @param cause the cause (that is saved for later retrieval by the
* {@link #getCause()} method). (A null value is
* permitted, and indicates that the cause is nonexistent or
* unknown.)
* @since 1.0
*/
public CacheException(Throwable cause) {
super(cause);
}
}
================================================
FILE: src/main/java/javax/cache/CacheManager.java
================================================
/**
* 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;
import javax.cache.configuration.Configuration;
import javax.cache.management.CacheMXBean;
import javax.cache.spi.CachingProvider;
import java.io.Closeable;
import java.lang.management.ManagementFactory;
import java.net.URI;
import java.util.Properties;
/**
* A {@link CacheManager} provides a means of establishing, configuring,
* acquiring, closing and destroying uniquely named {@link Cache}s.
*
* {@link Cache}s produced and owned by a {@link CacheManager} typically share
* common infrastructure, for example, a common {@link ClassLoader} and
* implementation specific {@link Properties}.
*
* Implementations of {@link CacheManager} may additionally provide and share
* external resources between the {@link Cache}s being managed, for example,
* the content of the managed {@link Cache}s may be stored in the same cluster.
*
* By default {@link CacheManager} instances are typically acquired through the
* use of a {@link CachingProvider}. Implementations however may additionally
* provide other mechanisms to create, acquire, manage and configure
* {@link CacheManager}s, including:
*
* The default {@link CacheManager} however can always be acquired using the
* default configured {@link CachingProvider} obtained by the {@link Caching}
* class. For example:
*
* Within a Java process {@link CacheManager}s and the {@link Cache}s they
* manage are scoped and uniquely identified by a {@link URI}, the meaning of
* which is implementation specific. To obtain the default {@link URI},
* {@link ClassLoader} and {@link Properties} for an implementation, consult the
* {@link CachingProvider} class.
*
*
* @author Greg Luck
* @author Yannis Cosmadopoulos
* @author Brian Oliver
* @see Caching
* @see CachingProvider
* @see Cache
* @since 1.0
*
*/
public interface CacheManager extends Closeable {
/**
* Get the {@link CachingProvider} that created and is responsible for
* the {@link CacheManager}.
*
* @return the CachingProvider or
* Implementations are not required to re-configure the
* {@link CacheManager} should modifications to the returned
* {@link Properties} be made.
*
* @return the Properties used to create the {@link CacheManager}
*/
Properties getProperties();
/**
* Creates a named {@link Cache} at runtime.
*
* If a {@link Cache} with the specified name is known to the {@link
* CacheManager}, a CacheException is thrown.
*
* If a {@link Cache} with the specified name is unknown the {@link
* CacheManager}, one is created according to the provided {@link Configuration}
* after which it becomes managed by the {@link CacheManager}.
*
* Prior to a {@link Cache} being created, the provided {@link Configuration}s is
* validated within the context of the {@link CacheManager} properties and
* implementation.
*
* Implementers should be aware that the {@link Configuration} may be used to
* configure other {@link Cache}s.
*
* There's no requirement on the part of a developer to call this method for
* each {@link Cache} an application may use. Implementations may support
* the use of declarative mechanisms to pre-configure {@link Cache}s, thus
* removing the requirement to configure them in an application. In such
* circumstances a developer may simply call either the
* {@link #getCache(String)} or {@link #getCache(String, Class, Class)}
* methods to acquire a previously established or pre-configured {@link Cache}.
*
* @param
* Use this method to check runtime key and value types.
*
* Use {@link #getCache(String)} where this check is not required.
*
* Implementations must ensure that the key and value types are the same as
* those configured for the {@link Cache} prior to returning from this method.
*
* Implementations may further perform type checking on mutative cache operations
* and throw a {@link ClassCastException} if these checks fail.
*
* Implementations that support declarative mechanisms for pre-configuring
* {@link Cache}s may return a pre-configured {@link Cache} instead of
*
* This method may only be used to acquire {@link Cache}s that were
* configured without runtime key and value types, or were configured
* to use Object.class key and value types.
*
* Use the {@link #getCache(String, Class, Class)} method to acquire
* {@link Cache}s with a check that the supplied key and value type parameters
* match the runtime types.
*
* Implementations that support declarative mechanisms for pre-configuring
* {@link Cache}s may return a pre-configured {@link Cache} instead of
*
* {@link java.util.Iterator}s returned by the {@link Iterable} are immutable.
* If the {@link Cache}s managed by the {@link CacheManager} change,
* the {@link Iterable} and associated {@link java.util.Iterator}s are not
* affected.
*
* {@link java.util.Iterator}s returned by the {@link Iterable} may not provide
* all of the {@link Cache}s managed by the {@link CacheManager}. For example:
* Internally defined or platform specific {@link Cache}s that may be accessible
* by a call to {@link #getCache(String)} or {@link #getCache(String, Class,
* Class)} may not be present in an iteration.
*
* @return an {@link Iterable} over the names of managed {@link Cache}s.
* @throws IllegalStateException if the {@link CacheManager}
* is {@link #isClosed()}
* @throws SecurityException when the operation could not be performed
* due to the current security settings
*/
Iterable
* This is equivalent to the following sequence of method calls:
*
* From the time this method is called, the specified {@link Cache} is not
* available for operational use. An attempt to call an operational method on
* the {@link Cache} will throw an {@link IllegalStateException}.
*
* @param cacheName the cache to destroy
* @throws IllegalStateException if the {@link CacheManager}
* {@link #isClosed()}
* @throws NullPointerException if cacheName is null
* @throws SecurityException when the operation could not be performed
* due to the current security settings
*/
void destroyCache(String cacheName);
/**
* Controls whether management is enabled. If enabled the {@link CacheMXBean}
* for each cache is registered in the platform MBean server. The platform
* MBeanServer is obtained using
* {@link ManagementFactory#getPlatformMBeanServer()}.
*
* Management information includes the name and configuration information for
* the cache.
*
* Each cache's management object must be registered with an ObjectName that
* is unique and has the following type and attributes:
*
* Type:
*
* Required Attributes:
*
* Each cache's statistics object must be registered with an ObjectName that
* is unique and has the following type and attributes:
*
* Type:
*
* Required Attributes:
*
* For each {@link Cache} managed by the {@link CacheManager}, the
* {@link Cache#close()} method will be invoked, in no guaranteed order.
*
* If a {@link Cache#close()} call throws an exception, the exception will be
* ignored.
*
* After executing this method, the {@link #isClosed()} method will return
*
* All attempts to close a previously closed {@link CacheManager} will be
* ignored.
*
* Closing a CacheManager does not necessarily destroy the contents of the
* Caches in the CacheManager.
*
* It simply signals that the CacheManager is no longer required by the application
* and that future uses of a specific CacheManager instance should not be permitted.
*
* Depending on the implementation and Cache topology,
* (e.g. a storage-backed or distributed cache), the contents of closed Caches
* previously referenced by the CacheManager, may still be available and accessible
* by other applications.
*
* @throws SecurityException when the operation could not be performed due to the
* current security settings
*/
void close();
/**
* Determines whether the {@link CacheManager} instance has been closed. A
* {@link CacheManager} is considered closed if;
*
* This method generally cannot be called to determine whether the
* {@link CacheManager} is valid or invalid. A typical client can determine
* that a {@link CacheManager} is invalid by catching any exceptions that
* might be thrown when an operation is attempted.
*
* @return true if this {@link CacheManager} instance is closed; false if it
* is still open
*/
boolean isClosed();
/**
* Provides a standard mechanism to access the underlying concrete caching
* implementation to provide access to further, proprietary features.
*
* If the provider's implementation does not support the specified class,
* the {@link IllegalArgumentException} is thrown.
*
* @param
* While defined as part of the specification, its use is not required.
* Applications and/or containers may instead choose to directly instantiate a
* {@link CachingProvider} implementation based on implementation specific
* instructions.
*
* When using the {@link Caching} class, {@link CachingProvider} implementations
* are automatically discovered when they follow the conventions outlined by the
* Java Development Kit {@link ServiceLoader} class.
*
* Although automatically discovered, applications that choose to use this class
* should not make assumptions regarding the order in which implementations are
* returned by the {@link #getCachingProviders()} or
* {@link #getCachingProviders(ClassLoader)} methods.
*
* For a {@link CachingProvider} to be automatically discoverable by the
* {@link Caching} class, the fully qualified class name of the
* {@link CachingProvider} implementation must be declared in the following
* file:
*
* For example, in the reference implementation the contents of this file are:
*
* Alternatively when the fully qualified class name of a
* {@link CachingProvider} implementation is specified using the system property
*
* All {@link CachingProvider}s that are automatically detected or explicitly
* declared and loaded by the {@link Caching} class are maintained in an
* internal registry. Consequently when a previously loaded
* {@link CachingProvider} is requested, it will be simply returned from the
* internal registry, without reloading and/or instantiating the said
* implementation again.
*
* As required by some applications and containers, multiple co-existing
* {@link CachingProvider}s implementations, from the same or different
* implementors are permitted at runtime.
*
* To iterate through those that are currently registered a developer may use
* the following methods:
*
* Where multiple {@link CachingProvider}s are present, the
* {@link CachingProvider} returned by getters {@link #getCachingProvider()} and
* {@link #getCachingProvider(ClassLoader)} is undefined and as a result a
* {@link CacheException} will be thrown when attempted.
*
* @author Brian Oliver
* @author Greg Luck
* @author Yannis Cosmadopoulos
* @since 1.0
* @see ServiceLoader
* @see CachingProvider
*/
public final class Caching {
/**
* The
* By default this is the {@link Thread#getContextClassLoader()}.
*
* @return the default {@link ClassLoader}
*/
public static ClassLoader getDefaultClassLoader() {
return CACHING_PROVIDERS.getDefaultClassLoader();
}
/**
* Set the {@link ClassLoader} to use for API methods that don't explicitly
* require a {@link ClassLoader}, but internally use one.
*
* @param classLoader the {@link ClassLoader} or
* If a
* If a
* This method must be used for {@link Cache}s that were configured with
* runtime key and value types. Use {@link CacheManager#getCache(String)} for
* {@link Cache}s where these were not specified.
*
* Implementations must ensure that the key and value types are the same as
* those configured for the {@link Cache} prior to returning from this method.
*
* Implementations may further perform type checking on mutative cache operations
* and throw a {@link ClassCastException} if these checks fail.
*
* Implementations that support declarative mechanisms for pre-configuring
* {@link Cache}s may return a pre-configured {@link Cache} instead of
*
* By default this is the {@link Thread#getContextClassLoader()}.
*
* Should zero or more than one {@link CachingProvider}s be available, a
* CacheException is thrown.
*
* Should zero or more than one {@link CachingProvider}s be available, a
* CacheException is thrown.
*
* If a
* If a
* Following is an example of specifying a default cache name that is used by
* the annotations on the getDomain and deleteDomain methods. The annotation for
* getAllDomains would use the "allDomains" cache name specified in the method
* level annotation.
*
* If not specified defaults to:
* package.name.ClassName.methodName(package.ParameterType,package.ParameterType)
*
* Applicable for {@link CacheResult}, {@link CachePut}, {@link CacheRemove},
* and {@link CacheRemoveAll}
*/
@Nonbinding String cacheName() default "";
/**
* 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}
*
* Applicable for {@link CacheResult}, {@link CachePut}, {@link CacheRemove},
* and {@link CacheRemoveAll}
*/
@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 Arrays#deepHashCode(Object[])}
* and {@link Arrays#deepEquals(Object[], Object[])} with the array returned by
* {@link CacheKeyInvocationContext#getKeyParameters()}
*
* Used with {@link CacheResolver#resolveCache(CacheInvocationContext)} to
* determine the {@link javax.cache.Cache} to use at runtime for the method
* invocation.
*
* @param The type of annotation this context information is for. One of
* {@link CacheResult}, {@link CachePut}, {@link CacheRemove}, or {@link
* CacheRemoveAll}.
* @author Eric Dalquist
* @see CacheResolver
*/
public interface CacheInvocationContext
extends CacheMethodDetails {
/**
* @return The object the intercepted method was invoked on.
*/
Object getTarget();
/**
* Returns a clone of the array of all method parameters.
*
* @return An array of all parameters for the annotated method
*/
CacheInvocationParameter[] getAllParameters();
/**
* Return an object of the specified type to allow access to the
* provider-specific API. If the provider's
* implementation does not support the specified class, the {@link
* IllegalArgumentException} is thrown.
*
* @param
* Implementations must be thread-safe.
*
* @author Eric Dalquist
* @since 1.0
*/
public interface CacheKeyGenerator {
/**
* Called for each intercepted method invocation to generate a suitable
* cache key (as a {@link GeneratedCacheKey}) from the
* {@link CacheKeyInvocationContext} data.
*
* @param cacheKeyInvocationContext Information about the intercepted method invocation
* @return A non-null cache key for the invocation.
*/
GeneratedCacheKey generateCacheKey(CacheKeyInvocationContext cacheKeyInvocationContext);
}
================================================
FILE: src/main/java/javax/cache/annotation/CacheKeyInvocationContext.java
================================================
/**
* 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 java.lang.annotation.Annotation;
/**
* Runtime information about an intercepted method invocation for a method
* annotated with {@link CacheResult}, {@link CachePut}, or
* {@link CacheRemove}.
*
* Used with {@link CacheKeyGenerator#generateCacheKey(CacheKeyInvocationContext)}
* to generate a {@link GeneratedCacheKey} for the invocation.
*
* @param The type of annotation this context information is for. One of
* {@link CacheResult}, {@link CachePut}, or {@link CacheRemove}.
* @author Eric Dalquist
* @see CacheKeyGenerator
*/
public interface CacheKeyInvocationContext
extends CacheInvocationContext {
/**
* Returns a clone of the array of all method parameters to be used by the
* {@link
* CacheKeyGenerator} in creating a {@link GeneratedCacheKey}. The returned array
* may be the same as or a subset of the array returned by
* {@link #getAllParameters()}
*
* Parameters in this array are selected by the following rules:
*
* Used with {@link CacheResolverFactory#getCacheResolver(CacheMethodDetails)} to
* determine the {@link CacheResolver} to use with the method.
*
* @param The type of annotation this context information is for. One of
* {@link CacheResult}, {@link CachePut}, {@link CacheRemove}, or
* {@link CacheRemoveAll}.
* @author Eric Dalquist
* @see CacheResolverFactory
*/
public interface CacheMethodDetails {
/**
* The annotated method
*
* @return The annotated method
*/
Method getMethod();
/**
* An immutable Set of all Annotations on this method
*
* @return An immutable Set of all Annotations on this method
*/
Set
* The cache name is determined by first looking at the cacheName attribute of
* the method level annotation. If that attribute is not set then the class
* level {@link CacheDefaults} annotation is checked. If that annotation does
* not exist or does not have its cacheName attribute set then the following
* cache name generation rules are followed:
*
* "fully qualified class name"."method name"("fully qualified parameter class
* names")
*
* For example:
*
* Results in the cache name: "my.app.DomainDao.getDomain(java.lang.String,int)"
*
* @return The fully resolved cache name
*/
String getCacheName();
}
================================================
FILE: src/main/java/javax/cache/annotation/CachePut.java
================================================
/**
* 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;
import java.util.Arrays;
/**
* When a method annotated with {@link CachePut} is invoked a {@link
* GeneratedCacheKey} will be generated and {@link Cache#put(Object,
* Object)} will be invoked on the specified cache storing the value marked with
* {@link CacheValue}.
*
* The default behavior is to call {@link Cache#put(Object, Object)}
* after the annotated method is invoked, this behavior can be changed by setting
* {@link #afterInvocation()} to false in which case
* {@link 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 {@link CacheValue} annotation is used to designate which
* parameter should be stored in the "domainDao" cache.
*
* Exception Handling, only used if {@link #afterInvocation()} is true.
*
* 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 "";
/**
* When {@link 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
* {@link #cacheFor()} and {@link #noCacheFor()} will be followed.
*/
@Nonbinding boolean afterInvocation() default true;
/**
* 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 Arrays#deepHashCode(Object[])}
* and {@link Arrays#deepEquals(Object[], Object[])} with the array
* returned by {@link CacheKeyInvocationContext#getKeyParameters()}
*
* @see CacheKey
*/
@Nonbinding Class cacheKeyGenerator()
default CacheKeyGenerator.class;
/**
* Defines zero (0) or more exception {@link Class classes}, that must be a
* subclass of {@link Throwable}, indicating the exception types that must
* cause the parameter to be cached. Only used if {@link #afterInvocation()} is
* true.
*/
@Nonbinding Class[] cacheFor() default {};
/**
* Defines zero (0) or more exception {@link Class Classes}, which must be a
* subclass of {@link Throwable}, indicating which exception types must
* not cause the parameter to be cached. Only used if
* {@link #afterInvocation()} is true.
*/
@Nonbinding Class[] noCacheFor() default {};
}
================================================
FILE: src/main/java/javax/cache/annotation/CacheRemove.java
================================================
/**
* 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 CacheRemove} is invoked a {@link
* GeneratedCacheKey} will be generated and {@link Cache#remove(Object)} will be
* invoked on the specified cache.
*
* The default behavior is to call {@link Cache#remove(Object)} after
* the annotated method is invoked, this behavior can be changed by setting
* {@link #afterInvocation()} to false in which case
* {@link Cache#remove(Object)} will be called before the annotated
* method is invoked.
*
* Example of removing a specific Domain object from the "domainCache". A {@link
* GeneratedCacheKey} will be generated from the String and int parameters and
* used to call {@link Cache#remove(Object)} after the deleteDomain
* method completes successfully.
*
* Exception Handling, only used if {@link #afterInvocation()} is true.
*
* If not specified defaults first to {@link CacheDefaults#cacheName()},
* and if that is not set then to:
* package.name.ClassName.methodName(package.ParameterType,package.ParameterType)
*/
@Nonbinding String cacheName() default "";
/**
* When {@link Cache#remove(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 remove will not be
* executed.
*/
@Nonbinding boolean afterInvocation() default true;
/**
* 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;
/**
* Defines zero (0) or more exception {@link Class classes}, that must be a
* subclass of {@link Throwable}, indicating the exception types that must cause
* a cache eviction. Only used if {@link #afterInvocation()} is true.
*/
@Nonbinding Class[] evictFor() 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 cause a cache eviction. Only used if {@link #afterInvocation()} is
* true.
*/
@Nonbinding Class[] noEvictFor() default {};
}
================================================
FILE: src/main/java/javax/cache/annotation/CacheRemoveAll.java
================================================
/**
* 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 CacheRemoveAll} is invoked all elements in
* the specified cache will be removed via the
* {@link Cache#removeAll()} method
*
* The default behavior is to call {@link Cache#removeAll()} after the
* annotated method is invoked, this behavior can be changed by setting {@link
* #afterInvocation()} to false in which case {@link Cache#removeAll()}
* will be called before the annotated method is invoked.
*
* Example of removing all Domain objects from the "domainCache". {@link
* Cache#removeAll()} will be called after deleteAllDomains() returns
* successfully.
*
* Exception Handling, only used if {@link #afterInvocation()} is true.
*
* 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 "";
/**
* When {@link Cache#removeAll()} 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 removeAll will not be
* executed.
*/
@Nonbinding boolean afterInvocation() default true;
/**
* 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;
/**
* Defines zero (0) or more exception {@link Class classes}, that must be a
* subclass of {@link Throwable}, indicating the exception types that must
* cause a cache eviction. Only used if {@link #afterInvocation()} is true.
*/
@Nonbinding Class[] evictFor() 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 cause a cache eviction. Only used if {@link #afterInvocation()} is
* true.
*/
@Nonbinding Class[] noEvictFor() default {};
}
================================================
FILE: src/main/java/javax/cache/annotation/CacheResolver.java
================================================
/**
* 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 java.lang.annotation.Annotation;
/**
* Determines the {@link Cache} to use for an intercepted method invocation.
*
* Implementations MUST be thread-safe.
*
* @author Eric Dalquist
* @see CacheResolverFactory
* @since 1.0
*/
public interface CacheResolver {
/**
* Resolve the {@link Cache} to use for the {@link CacheInvocationContext}.
*
* @param
* Implementations MUST be thread-safe.
*
* @author Eric Dalquist
* @since 1.0
*/
public interface CacheResolverFactory {
/**
* Get the {@link CacheResolver} used at runtime for resolution of the
* {@link Cache} for the {@link CacheResult}, {@link CachePut},
* {@link CacheRemove}, or {@link CacheRemoveAll} annotation.
*
* @param cacheMethodDetails The details of the annotated method to get the
* {@link CacheResolver} for. @return The {@link
* CacheResolver} instance to be
* used by the interceptor.
*/
CacheResolver getCacheResolver(CacheMethodDetails
cacheMethodDetails);
/**
* Get the {@link CacheResolver} used at runtime for resolution of the {@link
* Cache} for the {@link CacheResult} annotation to cache exceptions.
*
* Will only be called if {@link CacheResult#exceptionCacheName()} is not empty.
*
* @param cacheMethodDetails The details of the annotated method to get the
* {@link CacheResolver} for.
* @return The {@link CacheResolver} instance to be used by the interceptor.
*/
CacheResolver getExceptionCacheResolver(CacheMethodDetails
* 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
*
* With no {@link #cacheName()} specified a cache name of
* "my.app.DomainDao.getDomain(java.lang.String,int)" will be generated.
*
* Example using the {@link GeneratedCacheKey} annotation so that only the domainId
* parameter is used in key generation:
*
* If exception caching is enabled via specification of
* {@link #exceptionCacheName()} the following rules are used to determine if a
* thrown exception is cached:
*
* The name of 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 {};
}
================================================
FILE: src/main/java/javax/cache/annotation/CacheValue.java
================================================
/**
* 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 java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Marks the parameter to be cached for a method annotated with {@link CachePut}.
*
* @author Eric Dalquist
* @author Rick Hightower
* @see CachePut
* @since 1.0
*/
@Target({ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface CacheValue {
}
================================================
FILE: src/main/java/javax/cache/annotation/GeneratedCacheKey.java
================================================
/**
* 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 java.io.Serializable;
/**
* A {@link Serializable}, immutable, thread-safe object that is used as a key,
* automatically generated by a {@link CacheKeyGenerator}.
*
* The implementation MUST follow the Java contract for {@link Object#hashCode()}
* and {@link Object#equals(Object)} to ensure correct behavior.
*
* It is recommended that implementations also override {@link Object#toString()}
* and provide a human-readable string representation of the key.
*
* @author Eric Dalquist
* @see CacheKeyGenerator
* @since 1.0
*/
public interface GeneratedCacheKey extends Serializable {
/**
* The immutable hash code of the cache key.
*
* @return The hash code of the object
* @see Object#hashCode()
*/
@Override
int hashCode();
/**
* Compare this {@link GeneratedCacheKey} with another. If the two objects
* are equal their {@link #hashCode()} values MUST be equal as well.
*
* @param object The other object to compare to.
* @return true if the objects are equal
* @see Object#equals(Object)
*/
@Override
boolean equals(Object object);
}
================================================
FILE: src/main/java/javax/cache/annotation/package-info.java
================================================
/**
* 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.
*/
/**
* The annotations in this package provide method interceptors for user supplied
* classes.
*
* In the case of a the {@link javax.cache.annotation.CacheResult} annotation,
* if the cache can satisfy the request a result is returned by the method from
* cache, not from method execution. For the mutative annotations such as
* {@link javax.cache.annotation.CacheResult} the annotation allows the cached
* value to be mutated so that it will be correct the next time
* {@link javax.cache.annotation.CacheResult} is used.
*
* Any operations against a cache via an annotation will have the same behaviour
* as if the {@link javax.cache.annotation.CacheResult} methods were used. So
* if the same underlying cache is used for an annotation and a direct API call,
* the same data would be returned. Annotations therefore provide an additional
* API for interacting with caches.
*
* To use these annotations you'll need a library or framework that processes
* these annotations and intercepts calls to your application objects
* to provide the caching behaviour. This would commonly be provided by a
* dependency injection framework such as defined by CDI in Java EE.
*
* @author Eric Dalquist
* @author Greg Luck
* @since 1.0
*/
package javax.cache.annotation;
================================================
FILE: src/main/java/javax/cache/configuration/CacheEntryListenerConfiguration.java
================================================
/**
* 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.configuration;
import javax.cache.event.CacheEntryEventFilter;
import javax.cache.event.CacheEntryListener;
import java.io.Serializable;
/**
* Defines the configuration requirements for a
* {@link CacheEntryListener} and a {@link Factory} for its
* creation.
*
* @param
* When
* The properties provided by instances of this interface are used by
* {@link javax.cache.CacheManager}s to configure {@link javax.cache.Cache}s.
*
* Implementations of this interface must override {@link Object#hashCode()} and
* {@link Object#equals(Object)} as
* {@link javax.cache.configuration.CompleteConfiguration}s are often compared at
* runtime.
*
* @param
* When in "read-through" mode, cache misses that occur due to cache entries
* not existing as a result of performing a "get" will appropriately
* cause the configured {@link javax.cache.integration.CacheLoader} to be
* invoked.
*
* The default value is
* When in "write-through" mode, cache updates that occur as a result of
* performing "put" operations called via one of
* {@link javax.cache.Cache#put(Object, Object)},
* {@link javax.cache.Cache#getAndRemove(Object)},
* {@link javax.cache.Cache#removeAll()},
* {@link javax.cache.Cache#getAndPut(Object, Object)}
* {@link javax.cache.Cache#getAndRemove(Object)},
* {@link javax.cache.Cache#getAndReplace(Object,
* Object)}, {@link javax.cache.Cache#invoke(Object,
* javax.cache.processor.EntryProcessor,
* Object...)}, {@link javax.cache.Cache#invokeAll(java.util.Set,
* javax.cache.processor.EntryProcessor, Object...)} will appropriately cause
* the configured {@link javax.cache.integration.CacheWriter} to be invoked.
*
* The default value is
* The default value is
* The default value is
* A CacheLoader should be configured for "Read Through" caches to load values
* when a cache miss occurs using either the
* {@link javax.cache.Cache#get(Object)} and/or
* {@link javax.cache.Cache#getAll(java.util.Set)} methods.
*
* The default value is
* The default value is
* The default value is a {@link javax.cache.configuration.Factory} that will
* produce a {@link javax.cache.expiry.EternalExpiryPolicy} instance.
*
* @return the {@link javax.cache.configuration.Factory} for
* {@link javax.cache.expiry.ExpiryPolicy} (must not be
* The properties provided by instances of this interface are used by
* {@link CacheManager}s to configure {@link Cache}s.
*
* Implementations of this interface must override {@link Object#hashCode()} and
* {@link Object#equals(Object)} as {@link Configuration}s are often compared at
* runtime.
*
* @param
* When false, both keys and values are stored by reference.
* Caches stored by reference are capable of mutation by any threads holding
* the reference. The effects are:
*
* When a cache is storeByValue, any mutation to the key or value does not
* affect the key of value stored in the cache.
*
* The default value is
* Implementations may choose not to construct a new instance, but instead
* return a previously created instance.
*
* Implementations must correctly implement {@link Object#equals(Object)} and
* {@link Object#hashCode()} as {@link Factory}s are often compared with each
* other for equivalence.
*
* @param
* {@link Factory} is used by {@link MutableConfiguration} to avoid adding
* non-Serializable instances that would assume usage in the local JVM.
*
* Two styles of builder are available:
*
* The specified class must have a no-args constructor.
*
* @param clazz the class of instances to be produced by the returned
* {@link Factory}
* @param
* The specified class must have a no-args constructor.
*
* @param className the class of instances to be produced by the returned
* {@link Factory}
* @param
* If T is not Serializable use {@link #factoryOf(Class)} or
* {@link #factoryOf(String)}.
*
* @param instance the Serializable instance the {@link Factory} will return
* @param
* Creates a default configuration. Default configurations have no
* runtime type checking and are set for eternal expiry.
*
* To enable runtime type enforcement, if supported by the implementation, call
* {@link #setTypes} after construction.
*
* After construction set any other configuration parameters in the
* fluent style. e.g.
*
* This is used by {@link CacheManager} to ensure that the key and value
* types are the same as those configured for the {@link Cache} prior to
* returning a requested cache from this method.
*
* Implementations may further perform type checking on mutative cache operations
* and throw a {@link ClassCastException} if these checks fail.
*
* @param keyType the expected key type
* @param valueType the expected value type
* @return the {@link MutableConfiguration} to permit fluent-style method calls
* @throws NullPointerException should the key or value type be null
* @see CacheManager#getCache(String, Class, Class)
*/
public MutableConfiguration
* Only one expiry policy can be set for a cache. The last policy applied
* before cache construction will be the one used.
* @param factory the {@link ExpiryPolicy} {@link Factory}
* @return the {@link MutableConfiguration} to permit fluent-style method calls
*/
public MutableConfiguration
* It is an invalid configuration to set this to true without specifying a
* {@link CacheLoader} {@link Factory}.
*
* @param isReadThrough
* It is an invalid configuration to set this to true without specifying a
* {@link CacheWriter} {@link Factory}.
*
* @param isWriteThrough
* Statistics may be enabled or disabled at runtime via
* {@link CacheManager#enableStatistics(String, boolean)}.
*
* @param enabled true to enable statistics, false to disable.
* @return the {@link MutableConfiguration} to permit fluent-style method calls
*/
public MutableConfiguration
* Management may be enabled or disabled at runtime via
* {@link CacheManager#enableManagement(String, boolean)}.
*
* @param enabled true to enable statistics, false to disable.
* @return the {@link MutableConfiguration} to permit fluent-style method calls
*/
public MutableConfiguration
* Rather than configuration accepting user instances of interfaces for maximum
* portability factories are configured instead, so that instances can be
* instantiated where needed. To aid in this, FactoryBuilder can build factories
* of the required type as shown in the following example.
*
* {@link javax.cache.configuration.OptionalFeature}, though not specific to
* cache configuration, allows application to determine the optional features
* supported at runtime.
*
* @author Greg Luck
* @since 1.0
*/
package javax.cache.configuration;
================================================
FILE: src/main/java/javax/cache/event/CacheEntryCreatedListener.java
================================================
/**
* 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.event;
/**
* Invoked after a cache entry is created, or if a batch call is made, after the
* entries are created.
*
* If an entry for the key existed prior to the operation it is not invoked,
* instead {@link CacheEntryUpdatedListener} is invoked.
*
* @param
* The value will be available
* for {@link CacheEntryCreatedListener} and {@link CacheEntryUpdatedListener}.
* Returns the same value as {@link #getOldValue()} for
* {@link CacheEntryExpiredListener} and {@link CacheEntryRemovedListener}.
* Cache clients that need to maintain compatibility with JSR107 version 1.0
* cache implementations, need to use this method for retrieving the expired
* or removed value. When using cache implementations compatible with JSR107
* version 1.1, clients should prefer the method {@link #getOldValue()}.
*
* @return the value corresponding to this entry
* @see #getOldValue()
*/
@Override
public abstract V getValue();
/**
* Returns the previous value that existed for entry in the cache before
* modification or removal.
*
* The old value will be available
* for {@link CacheEntryUpdatedListener}, {@link CacheEntryExpiredListener}
* and {@link CacheEntryRemovedListener}
* if {@link CacheEntryListenerConfiguration#isOldValueRequired()} is true.
* The old value may be available for {@link CacheEntryUpdatedListener},
* {@link CacheEntryExpiredListener} and {@link CacheEntryRemovedListener}
* if {@link CacheEntryListenerConfiguration#isOldValueRequired()} is false.
*
* @return the previous value or
* A filter must not create side effects.
*
* @param
* Sub-interfaces exist for the various cache events allowing a listener to be
* created that implements only those listeners it is interested in.
*
* Listeners should be implemented with care. In particular it is important to
* consider their impact on performance and latency.
*
* Listeners:
*
* Listeners can only throw {@link CacheEntryListenerException}. Caching
* implementations must catch any other {@link Exception} from a listener, then
* wrap and rethrow it as a {@link CacheEntryListenerException}.
*
* A listener that mutates a cache on the CacheManager may cause a deadlock.
* Detection and response to deadlocks is implementation specific.
*
* @param
* These may be registered for callback notification of the cache events.
* The specific interface should be implemented for each event type a callback
* is desired on.
*
* Event notifications occur synchronously in the line of execution of the calling thread.
* The calling thread blocks until the listener has completed execution or thrown a {@link javax.cache.event.CacheEntryCreatedListener}.
*
* Listeners are invoked after the cache is updated. If the listener throws
* an {@link javax.cache.event.CacheEntryCreatedListener} this will propagate back to the caller but it does not affect the cache update
* as it already completed before the listener was called.
*
* @author Greg Luck
* @author Yannis Cosmadopoulos
* @since 1.0
*/
package javax.cache.event;
================================================
FILE: src/main/java/javax/cache/expiry/AccessedExpiryPolicy.java
================================================
/**
* 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.expiry;
import javax.cache.configuration.Factory;
import javax.cache.configuration.FactoryBuilder;
import java.io.Serializable;
/**
* An {@link ExpiryPolicy} that defines the expiry {@link Duration}
* of a Cache Entry based on the last time it was accessed. Accessed
* does not include a cache update.
*
* @author Greg Luck
* @author Brian Oliver
* @since 1.0
* @see ExpiryPolicy
*/
public final class AccessedExpiryPolicy implements ExpiryPolicy, Serializable {
/**
* The serialVersionUID required for {@link java.io.Serializable}.
*/
public static final long serialVersionUID = 201305101601L;
/**
* The {@link Duration} a Cache Entry should be available before it expires.
*/
private Duration expiryDuration;
/**
* Constructs an {@link AccessedExpiryPolicy} {@link ExpiryPolicy}.
*
* @param expiryDuration the {@link Duration} a Cache Entry should exist be
* before it expires after being accessed
*/
public AccessedExpiryPolicy(Duration expiryDuration) {
this.expiryDuration = expiryDuration;
}
/**
* Obtains a {@link Factory} for an Accessed {@link ExpiryPolicy}.
* @param duration The expiry duration
* @return a {@link Factory} for an Accessed {@link ExpiryPolicy}.
*/
public static FactoryreplaceExistingValues is true. If no loader
* is configured for the cache, no objects will be loaded. If a problem is
* encountered during the retrieving or loading of the objects,
* an exception is provided to the {@link CompletionListener}. Once the
* operation has completed, the specified CompletionListener is notified.
*
* except that the action is performed atomically.
*
* if (!cache.containsKey(key)) {}
* cache.put(key, value);
* return true;
* } else {
* return false;
* }
* (key==null ? k==null : key.equals(k)), that mapping is removed.
* (The cache can contain at most one such mapping.)
*
*
* except that the action is performed atomically.
*
* if (cache.containsKey(key) && equals(cache.get(key), oldValue) {
* cache.remove(key);
* return true;
* } else {
* return false;
* }
*
* except that the action is performed atomically.
*
* if (cache.containsKey(key)) {
* V oldValue = cache.get(key);
* cache.remove(key);
* return oldValue;
* } else {
* return null;
* }
*
* except that the action is performed atomically.
*
* if (cache.containsKey(key) && equals(cache.get(key), oldValue)) {
* cache.put(key, newValue);
* return true;
* } else {
* return false;
* }
*
* except that the action is performed atomically.
*
* if (cache.containsKey(key)) {
* cache.put(key, value);
* return true;
* } else {
* return false;
* }
* except that the action is performed atomically.
*
* if (cache.containsKey(key)) {
* V oldValue = cache.get(key);
* cache.put(key, value);
* return oldValue;
* } else {
* return null;
* }
*
*
*
* @param keys the keys to remove
* @throws NullPointerException if keys is null or if it contains a null key
* @throws IllegalStateException if the cache is {@link #isClosed()}
* @throws CacheException if there is a problem during the remove
* @throws ClassCastException if the implementation is configured to perform
* runtime-type-checking, and the key or value
* types are incompatible with those that have been
* configured for the {@link Cache}
* @see CacheWriter#deleteAll
*/
void removeAll(Set keys);
/**
* Removes all of the mappings from this cache.
*
*
* If the cache is empty, the {@link CacheWriter} is not called.
* null value for a key.
* @throws NullPointerException if keys or {@link EntryProcessor} are null
* @throws IllegalStateException if the cache is {@link #isClosed()}
* @throws ClassCastException if the implementation is configured to perform
* runtime-type-checking, and the key or value
* types are incompatible with those that have been
* configured for the {@link Cache}
* @see EntryProcessor
*/
null if the {@link Cache} is not
* managed
*/
CacheManager getCacheManager();
/**
* Closing a {@link Cache} signals to the {@link CacheManager} that produced or
* owns the {@link Cache} that it should no longer be managed. At this
* point in time the {@link CacheManager}:
*
*
* Once closed any attempt to use an operational method on a Cache will throw an
* {@link IllegalStateException}.
* close
* method on configured {@link CacheLoader},
* {@link CacheWriter}, registered {@link CacheEntryListener}s and
* {@link ExpiryPolicy} instances that implement the java.io.Closeable
* interface.
*
*
*
*
* new operator to create a
* concrete implementation,
*
* CachingProvider provider = Caching.getCachingProvider();
* CacheManager manager = provider.getCacheManager();
* null if the {@link CacheManager}
* was created without using a {@link CachingProvider}
*/
CachingProvider getCachingProvider();
/**
* Get the URI of the {@link CacheManager}.
*
* @return the URI of the {@link CacheManager}
*/
URI getURI();
/**
* Get the {@link ClassLoader} used by the {@link CacheManager}.
*
* @return the {@link ClassLoader} used by the {@link CacheManager}
*/
ClassLoader getClassLoader();
/**
* Get the {@link Properties} that were used to create this
* {@link CacheManager}.
* null.
*
* @param null.
*
* @param
*
* followed by allowing the name of the {@link Cache} to be used for other
* {@link Cache} configurations.
* javax.cache:type=CacheConfiguration
*
*
*
* @param cacheName the name of the cache to register
* @param enabled true to enable management, false to disable.
* @throws IllegalStateException if the {@link CacheManager} or
* {@link Cache} {@link #isClosed()}
* @throws SecurityException when the operation could not be performed
* due to the current security settings
*/
void enableManagement(String cacheName, boolean enabled);
/**
* Enables or disables statistics gathering for a managed {@link Cache} at
* runtime.
* javax.cache:type=CacheStatistics
*
*
*
* @param cacheName the name of the cache to register
* @param enabled true to enable statistics, false to disable.
* @throws IllegalStateException if the {@link CacheManager} or
* {@link Cache} {@link #isClosed()}
* @throws NullPointerException if cacheName is null
* @throws SecurityException when the operation could not be performed
* due to the current security settings
*/
void enableStatistics(String cacheName, boolean enabled);
/**
* Closes the {@link CacheManager}.
* true.
*
*
*
* META-INF/services/javax.cache.spi.CachingProvider
*
* This file must be resolvable via the class path.
* org.jsr107.ri.RICachingProvider
* javax.cache.spi.cachingprovider, that implementation will be used
* as the default {@link CachingProvider}.
*
*
* To request a specific {@link CachingProvider} implementation, a developer
* should use either the {@link #getCachingProvider(String)} or
* {@link #getCachingProvider(String, ClassLoader)} method.
* javax.cache.spi.cachingprovider constant.
*/
public static final String JAVAX_CACHE_CACHING_PROVIDER = "javax.cache" +
".spi.CachingProvider";
/**
* The {@link CachingProviderRegistry} that tracks the {@link CachingProvider}s.
*/
private static final CachingProviderRegistry CACHING_PROVIDERS =
new CachingProviderRegistry();
/**
* No public constructor as all methods are static.
*/
private Caching() {
}
/**
* Obtains the {@link ClassLoader} to use for API methods that don't
* explicitly require a {@link ClassLoader} but internally require one.
* null if the
* calling {@link Thread#getContextClassLoader()} should
* be used
*/
public static void setDefaultClassLoader(ClassLoader classLoader) {
CACHING_PROVIDERS.setDefaultClassLoader(classLoader);
}
/**
* Obtains the default {@link CachingProvider} available via the
* {@link #getDefaultClassLoader()}.
*
* @return the {@link CachingProvider}
* @throws CacheException should zero, or more than one
* {@link CachingProvider} be available on the
* classpath, or it could not be loaded
* @throws SecurityException when the operation could not be performed
* due to the current security settings
*/
public static CachingProvider getCachingProvider() {
return CACHING_PROVIDERS.getCachingProvider();
}
/**
* Obtains the single {@link CachingProvider} visible to the specified
* {@link ClassLoader}.
*
* @param classLoader the {@link ClassLoader} to use for loading the
* {@link CachingProvider}
* @return the {@link CachingProvider}
* @throws CacheException should zero, or more than one
* {@link CachingProvider} be available on the
* classpath, or it could not be loaded
* @throws SecurityException when the operation could not be performed
* due to the current security settings
* @see #getCachingProviders(ClassLoader)
*/
public static CachingProvider getCachingProvider(ClassLoader classLoader) {
return CACHING_PROVIDERS.getCachingProvider(classLoader);
}
/**
* Obtains the {@link CachingProvider}s that are available via the
* {@link #getDefaultClassLoader()}.
* javax.cache.spi.cachingprovider system property is defined,
* only that {@link CachingProvider} specified by that property is returned.
* Otherwise all {@link CachingProvider}s that are available via a
* {@link ServiceLoader} for {@link CachingProvider}s using the default
* {@link ClassLoader} (including those previously requested via
* {@link #getCachingProvider(String)}) are returned.
*
* @return an {@link Iterable} of {@link CachingProvider}s loaded by the
* specified {@link ClassLoader}
*/
public static Iterablejavax.cache.spi.cachingprovider system property is defined,
* only that {@link CachingProvider} specified by that property is returned.
* Otherwise all {@link CachingProvider}s that are available via a
* {@link ServiceLoader} for {@link CachingProvider}s using the specified
* {@link ClassLoader} (including those previously requested via
* {@link #getCachingProvider(String, ClassLoader)}) are returned.
*
* @param classLoader the {@link ClassLoader} of the returned
* {@link CachingProvider}s
* @return an {@link Iterable} of {@link CachingProvider}s loaded by the
* specified {@link ClassLoader}
*/
public static IterableCachingProvider and CacheManager
* . For the full range of Cache look up methods see
* {@link CacheManager}.
* null.
* @param null the
* {@link Thread#getContextClassLoader()} will be used.
*/
private volatile ClassLoader classLoader;
/**
* Constructs a CachingProviderManager.
*/
public CachingProviderRegistry() {
this.cachingProviders = new WeakHashMapnull if the
* calling {@link Thread#getContextClassLoader()} should
* be used
*/
public void setDefaultClassLoader(ClassLoader classLoader) {
this.classLoader = classLoader;
}
/**
* Obtains the only {@link CachingProvider} defined by the
* {@link #getDefaultClassLoader()}.
* javax.cache.spi.cachingprovider system property is defined,
* only that {@link CachingProvider} specified by that property is returned.
* Otherwise all {@link CachingProvider}s that are available via a
* {@link ServiceLoader} for {@link CachingProvider}s using the default
* {@link ClassLoader} (and those explicitly requested via
* {@link #getCachingProvider(String)}) are returned.
* javax.cache.spi.cachingprovider system property is defined,
* only that {@link CachingProvider} specified by that property is returned.
* Otherwise all {@link CachingProvider}s that are available via a
* {@link ServiceLoader} for {@link CachingProvider}s using the specified
* {@link ClassLoader} (and those explicitly requested via
* {@link #getCachingProvider(String, ClassLoader)}) are returned.
*
*
* @author Rick Hightower
* @since 1.0
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface CacheDefaults {
/**
* The default name of the cache for the annotated class
*
* package my.app;
*
* @CacheDefaults(cacheName="domainCache")
* public class DomainDao {
* @CacheResult
* public Domain getDomain(String domainId, int index) {
* ...
* }
*
* @CacheRemove
* public void deleteDomain(String domainId, int index) {
* ...
* }
*
* @CacheResult(cacheName="allDomains")
* public List<Domain> getAllDomains() {
* ...
* }
* }
*
*
*
* @return An array of all parameters to be used in cache key generation
*/
CacheInvocationParameter[] getKeyParameters();
/**
* When a method is annotated with {@link CachePut} this is the parameter
* annotated with {@link CacheValue}
*
* @return The parameter to cache, will never be null for methods annotated with
* {@link CachePut}, will be null for methods not annotated with {@link
* CachePut}
*/
CacheInvocationParameter getValueParameter();
}
================================================
FILE: src/main/java/javax/cache/annotation/CacheMethodDetails.java
================================================
/**
* 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 java.lang.annotation.Annotation;
import java.lang.reflect.Method;
import java.util.Set;
/**
* Static information about a method annotated with one of:
* {@link CacheResult}, {@link CachePut}, {@link CacheRemove}, or {@link
* CacheRemoveAll}
*
*
* package my.app;
*
* public class DomainDao {
* @CacheResult
* public Domain getDomain(String domainId, int index) {
* ...
* }
* }
*
*
* package my.app;
*
* public class DomainDao {
* @CachePut(cacheName="domainCache")
* public void updateDomain(String domainId, int index, @CacheValue Domain
* domain) {
* ...
* }
* }
*
*
*
* @author Eric Dalquist
* @author Rick Hightower
* @see CacheValue
* @see CacheKey
* @since 1.0
*/
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface CachePut {
/**
* The name of the cache.
*
*
* package my.app;
*
* public class DomainDao {
* @CacheRemove(cacheName="domainCache")
* public void deleteDomain(String domainId, int index) {
* ...
* }
* }
*
*
*
* @author Eric Dalquist
* @author Rick Hightower
* @author Greg Luck
* @see CacheKey
* @since 1.0
*/
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface CacheRemove {
/**
* The name of the cache.
*
*
* package my.app;
*
* public class DomainDao {
* @CacheRemoveAll(cacheName="domainCache")
* public void deleteAllDomains() {
* ...
* }
* }
*
*
*
* @author Eric Dalquist
* @author Rick Hightower
* @since 1.0
*/
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface CacheRemoveAll {
/**
* /**
* The name of the cache.
* String and int parameters.
*
*
* package my.app;
*
* public class DomainDao {
* @CacheResult
* public Domain getDomain(String domainId, int index) {
* ...
* }
* }
*
*
* package my.app;
*
* public class DomainDao {
* @CacheResult
* public Domain getDomain(@CacheKey String domainId, Monitor mon) {
* ...
* }
* }
*
*
*
* @author Eric Dalquist
* @author Rick Hightower
* @see CacheKey
* @since 1.0
*/
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface CacheResult {
/**
* true if the old value is required by the
* {@link CacheEntryListener}
*/
boolean isOldValueRequired();
/**
* Obtains the {@link Factory} for the {@link CacheEntryEventFilter} that should be
* applied prior to notifying the {@link CacheEntryListener}.
* null no filtering is applied and all appropriate events
* are notified.
*
* @return the {@link Factory} for the
* {@link CacheEntryEventFilter} or null
* if no filtering is required
*/
Factorytrue if the thread that created the event should block
*/
boolean isSynchronous();
}
================================================
FILE: src/main/java/javax/cache/configuration/CompleteConfiguration.java
================================================
/**
* 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.configuration;
import javax.cache.expiry.ExpiryPolicy;
import javax.cache.integration.CacheLoader;
import javax.cache.integration.CacheWriter;
import java.io.Serializable;
/**
* A read-only representation of the complete JCache {@link javax.cache.Cache}
* configuration.
* false.
*
* @return true when a {@link javax.cache.Cache} is in
* "read-through" mode.
* @see #getCacheLoaderFactory()
*/
boolean isReadThrough();
/**
* Determines if a {@link javax.cache.Cache} should operate in write-through
* mode.
* false.
*
* @return true when a {@link javax.cache.Cache} is in
* "write-through" mode.
* @see #getCacheWriterFactory()
*/
boolean isWriteThrough();
/**
* Checks whether statistics collection is enabled in this cache.
* false.
*
* @return true if statistics collection is enabled
*/
boolean isStatisticsEnabled();
/**
* Checks whether management is enabled on this cache.
* false.
*
* @return true if management is enabled
*/
boolean isManagementEnabled();
/**
* Obtains the {@link javax.cache.configuration.CacheEntryListenerConfiguration}s
* for {@link javax.cache.event.CacheEntryListener}s to be configured on a
* {@link javax.cache.Cache}.
*
* @return an {@link Iterable} over the
* {@link javax.cache.configuration.CacheEntryListenerConfiguration}s
*/
Iterablenull.
*
* @return the {@link javax.cache.configuration.Factory} for the
* {@link javax.cache.integration.CacheLoader} or null if none has been set.
*/
Factorynull.
*
* @return the {@link javax.cache.configuration.Factory} for the
* {@link javax.cache.integration.CacheWriter} or null if none has been set.
*/
Factorynull)
*/
FactoryObject.class if the type is undefined
*/
ClassObject.class if the type is undefined
*/
Class
*
* Storage by reference only applies to the local heap. If an entry is moved off
* heap it will need to be transformed into a representation. Any mutations that
* occur after transformation may not be reflected in the cache.
* true.
*
* @return true if the cache is store by value
*/
boolean isStoreByValue();
}
================================================
FILE: src/main/java/javax/cache/configuration/Factory.java
================================================
/**
* 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.configuration;
import java.io.Serializable;
/**
* Constructs and returns a fully configured instance of a specific factory type.
*
*
*
* Factory instances can also be created in other ways.
*
* @author Brian Oliver
* @author Greg Luck
* @since 1.0
*/
public final class FactoryBuilder {
/**
* A private constructor to prevent instantiation.
*/
private FactoryBuilder() {
//deliberately empty - no instances allowed!
}
/**
* Constructs a {@link Factory} that will produce factory instances of the
* specified class.
* null if event
* filtering is not requried
* @return the {@link MutableCacheEntryListenerConfiguration} to permit
* fluent-style method calls
*/
public MutableCacheEntryListenerConfigurationtrue if the old value is required
* @return the {@link MutableCacheEntryListenerConfiguration} to permit
* fluent-style method calls
*/
public MutableCacheEntryListenerConfigurationtrue means block until notified
* @return the {@link MutableCacheEntryListenerConfiguration} to permit
* fluent-style method calls
*/
public MutableCacheEntryListenerConfiguration{@code
* CacheConfiguration
* @see #setTypes(Class, Class)
*/
public MutableConfiguration() {
//Due to erasure in generics the type will always be Object.class. i.e. cast is ignored
this.keyType = (ClassObject.class means type-safety checks are not required.
* null
* is specified the default {@link ExpiryPolicy} is used.
* true if read-through is required
* @return the {@link MutableConfiguration} to permit fluent-style method calls
*/
public MutableConfigurationtrue if write-through is required
* @return the {@link MutableConfiguration} to permit fluent-style method calls
*/
public MutableConfigurationtrue if store-by-value is required,
* false for store-by-reference
* @return the {@link MutableConfiguration} to permit fluent-style method calls
*/
public MutableConfiguration
*
* MutableConfiguration<String, Integer> config = new MutableConfiguration<String, Integer>();
*
* config.setTypes(String.class, Integer.class)
* .setStoreByValue(false)
* .setStatisticsEnabled(true)
* .setExpiryPolicyFactory(FactoryBuilder.factoryOf(
* new AccessedExpiryPolicy<String>(new Duration(TimeUnit.HOURS, 1))));
* null if there was no previous
* value or the previous value is not available
*/
public abstract V getOldValue();
/**
* Whether the old value is available. The old value will be available
* for {@link CacheEntryUpdatedListener}, {@link CacheEntryExpiredListener}
* and {@link CacheEntryRemovedListener}
* if {@link CacheEntryListenerConfiguration#isOldValueRequired()} is true.
* The old value may be available for {@link CacheEntryUpdatedListener},
* {@link CacheEntryExpiredListener} and {@link CacheEntryRemovedListener}
* if {@link CacheEntryListenerConfiguration#isOldValueRequired()} is false.
*
* @return true if the old value is definitely available
*/
public abstract boolean isOldValueAvailable();
/**
* Gets the event type of this event
*
* @return the event type.
*/
public final EventType getEventType() {
return eventType;
}
}
================================================
FILE: src/main/java/javax/cache/event/CacheEntryEventFilter.java
================================================
/**
* 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.event;
/**
* A function that may be used to check {@link CacheEntryEvent}s prior to being
* dispatched to {@link CacheEntryListener}s.
*
*
* Listeners follow the observer pattern. An exception thrown by a
* listener does not cause the cache operation to fail.
*