javax.cache.CacheManager Maven / Gradle / Ivy
/**
* 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:
*
* - making use of {@link java.util.ServiceLoader}s,
* - permitting the use of the
new operator to create a
* concrete implementation,
* - providing the construction through the use of one or more
* builders, and
* - through the use of dependency injection.
*
*
* The default {@link CacheManager} however can always be acquired using the
* default configured {@link CachingProvider} obtained by the {@link Caching}
* class. For example:
*
* CachingProvider provider = Caching.getCachingProvider();
* CacheManager manager = provider.getCacheManager();
*
*
* 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 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}.
*
* 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 the type of key
* @param the type of value
* @param the type of the Configuration
* @param cacheName the name of the {@link Cache}. Names should not use
* forward slashes(/) or colons(:), or start with
* java. or javax. These prefixes are reserved.
* @param configuration a {@link Configuration} for the {@link Cache}
* @throws IllegalStateException if the {@link CacheManager}
* {@link #isClosed()}
* @throws CacheException if there was an error configuring the
* {@link Cache}, which includes trying
* to create a cache that already exists.
* @throws IllegalArgumentException if the configuration is invalid
* @throws UnsupportedOperationException if the configuration specifies
* an unsupported feature
* @throws NullPointerException if the cache configuration or name
* is null
* @throws SecurityException when the operation could not be performed
* due to the current security settings
*/
> Cache createCache(String cacheName,
C configuration)
throws IllegalArgumentException;
/**
* Looks up a managed {@link Cache} given its name.
*
* 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
* null.
*
* @param the type of key
* @param the type of value
* @param cacheName the name of the managed {@link Cache} to acquire
* @param keyType the expected {@link Class} of the key
* @param valueType the expected {@link Class} of the value
* @return the Cache or null if it does exist or can't be pre-configured
* @throws IllegalStateException if the {@link CacheManager}
* is {@link #isClosed()}
* @throws ClassCastException if the specified key and/or value types are
* incompatible with the configured cache.
* @throws NullPointerException if either keyType or classType is null.
* @throws SecurityException when the operation could not be performed
* due to the current security settings
*/
Cache getCache(String cacheName, Class keyType,
Class valueType);
/**
* Looks up a managed {@link Cache} given its name.
*
* 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
* null.
*
* @param the type of key
* @param the type of value
* @param cacheName the name of the cache to look for
* @return the Cache or null if it does exist or can't be pre-configured
* @throws IllegalStateException if the CacheManager is {@link #isClosed()}
* @throws SecurityException when the operation could not be performed
* due to the current security settings
* @see #getCache(String, Class, Class)
*/
Cache getCache(String cacheName);
/**
* Obtains an {@link Iterable} over the names of {@link Cache}s managed by the
* {@link CacheManager}.
*
* {@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 getCacheNames();
/**
* Destroys a specifically named and managed {@link Cache}. Once destroyed
* a new {@link Cache} of the same name but with a different {@link
* Configuration} may be configured.
*
* This is equivalent to the following sequence of method calls:
*
* - {@link Cache#clear()}
* - {@link Cache#close()}
*
* followed by allowing the name of the {@link Cache} to be used for other
* {@link Cache} configurations.
*
* 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:
* javax.cache:type=CacheConfiguration
*
* Required Attributes:
*
* - CacheManager the URI of the CacheManager
*
- Cache the name of the Cache
*
*
* @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.
*
* Each cache's statistics object must be registered with an ObjectName that
* is unique and has the following type and attributes:
*
* Type:
* javax.cache:type=CacheStatistics
*
* Required Attributes:
*
* - CacheManager the URI of the CacheManager
*
- Cache the name of the Cache
*
*
* @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}.
*
* 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
* true.
*
* 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;
*
* - the {@link #close()} method has been called
* - the associated {@link #getCachingProvider()} has been closed, or
* - the {@link CacheManager} has been closed using the associated
* {@link #getCachingProvider()}
*
*
* 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 the type of the underlying {@link CacheManager}
* @param clazz the proprietary class or interface of the underlying concrete
* {@link CacheManager}. It is this type that is returned.
* @return an instance of the underlying concrete {@link CacheManager}
* @throws IllegalArgumentException if the caching provider doesn't support the
* specified class.
* @throws SecurityException when the operation could not be performed
* due to the current security settings
*/
T unwrap(java.lang.Class clazz);
}