API Extensions
User Managed Cache
If you use a UserManagedCache, you need to configure all required services by hand.
The UserManagedCache class extends the Cache class by offering additional methods:
init() - initializes the cache
close() - releases the cache resources
getStatus() - returns a status
The init and close methods deal with the lifecycle of the cache and need to be called explicitly, whereas these methods are hidden when the cache is inside a CacheManager.
The interface definition is shown in this code:
package org.ehcache;
import java.io.Closeable;
/**
* Represents a {@link Cache} that is not managed by a
* {@link org.ehcache.CacheManager CacheManager}.
* <P>
* These caches must be {@link #close() closed} in order to release
* all their resources.
* </P>
*
* @param <K> the key type for the cache
* @param <V> the value type for the cache
*/
public interface UserManagedCache<K, V> extends Cache<K, V>, Closeable {
/**
* Transitions this {@code UserManagedCache} to
* {@link org.ehcache.Status#AVAILABLE AVAILABLE}.
* <P>
* If an error occurs before the {@code UserManagedCache} is {@code AVAILABLE},
* it will revert to {@link org.ehcache.Status#UNINITIALIZED UNINITIALIZED}
* and attempt to properly release all resources.
* </P>
*
* @throws IllegalStateException if the {@code UserManagedCache} is not
* {@code UNINITIALIZED}
* @throws StateTransitionException if the {@code UserManagedCache} could not
* be made {@code AVAILABLE}
*/
void init() throws StateTransitionException;
/**
* Transitions this {@code UserManagedCache} to
* {@link Status#UNINITIALIZED UNINITIALIZED}.
* <P>
* This will release all resources held by this cache.
* </P>
* <P>
* Failure to release a resource will not prevent other resources from being
* released.
* </P>
*
* @throws StateTransitionException if the {@code UserManagedCache} could not
* reach {@code UNINITIALIZED} cleanly
* @throws IllegalStateException if the {@code UserManagedCache} is not
* {@code AVAILABLE}
*/
@Override
void close() throws StateTransitionException;
/**
* Returns the current {@link org.ehcache.Status Status} of this
* {@code UserManagedCache}.
*
* @return the current {@code Status}
*/
Status getStatus();
}
User Managed Persistent Cache
A user managed persistent cache holds cached data in a persistent store such as disk, so that the stored data can outlive the JVM in which your caching application runs.
If you want to create a user managed persistent cache, there is an additional interface PersistentUserManagedCache that extends UserManagedCache and adds the destroy method.
The destroy method deletes all data structures, including data stored persistently on disk, for a PersistentUserManagedCache.
The destroy method deals with the lifecycle of the cache and needs to be called explicitly.
The interface definition is shown in this code:
package org.ehcache;
/**
* A {@link UserManagedCache} that holds data that can outlive the JVM.
*
* @param <K> the key type for the cache
* @param <V> the value type for the cache
*/
public interface PersistentUserManagedCache<K, V>
extends UserManagedCache<K, V> {
/**
* Destroys all persistent data structures for this
* {@code PersistentUserManagedCache}.
*
* @throws java.lang.IllegalStateException if state
* {@link org.ehcache.Status#MAINTENANCE MAINTENANCE} couldn't be reached
* @throws CachePersistenceException if the persistent data cannot be destroyed
*/
void destroy() throws CachePersistenceException;
}