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