org.apache.jcs.access

Class CacheAccess

java.lang.Object

org.apache.jcs.access.CacheAccess

All Implemented Interfaces:

ICacheAccess

Direct Known Subclasses:

GroupCacheAccess

public class CacheAccess
extends java.lang.Object
implements ICacheAccess

This class provides an interface for all types of access to the cache.

An instance of this class is tied to a specific cache region. Static methods are provided to get such instances.

Using this class you can retrieve an item, the item's wrapper, and the element's configuration. You can also put an item in the cache, remove an item, and clear a region.

The JCS class is the preferred way to access these methods.

Field Summary

Fields

Modifier and Type	Field and Description
protected CompositeCache	cacheControl The cache that a given instance of this class provides access to.

Constructor Summary

Constructors

Constructor and Description
CacheAccess(CompositeCache cacheControl) Constructor for the CacheAccess object.

Method Summary

Methods

Modifier and Type	Method and Description
void	clear() Removes all of the elements from a region.
static CacheAccess	defineRegion(java.lang.String name) Define a new cache region with the given name.
static CacheAccess	defineRegion(java.lang.String name, ICompositeCacheAttributes cattr) Define a new cache region with the specified name and attributes.
static CacheAccess	defineRegion(java.lang.String name, ICompositeCacheAttributes cattr, IElementAttributes attr) Define a new cache region with the specified name and attributes and return a CacheAccess to it.
void	destroy() Deprecated.
void	destroy(java.lang.Object name) Deprecated. use remove
void	dispose() Dispose this region.
protected static void	ensureCacheManager() Helper method which checks to make sure the cacheMgr class field is set, and if not requests an instance from CacheManagerFactory.
int	freeMemoryElements(int numberToFree) This instructs the memory cache to remove the numberToFree according to its eviction policy.
java.lang.Object	get(java.lang.Object name) Retrieve an object from the cache region this instance provides access to.
static CacheAccess	getAccess(java.lang.String region) Get a CacheAccess instance for the given region.
static CacheAccess	getAccess(java.lang.String region, ICompositeCacheAttributes icca) Get a CacheAccess instance for the given region with the given attributes.
ICompositeCacheAttributes	getCacheAttributes() Gets the ICompositeCacheAttributes of the cache region.
ICacheElement	getCacheElement(java.lang.Object name) This method returns the ICacheElement wrapper which provides access to element info and other attributes.
java.util.Map	getCacheElements(java.util.Set names) Get multiple elements from the cache based on a set of cache keys.
IElementAttributes	getDefaultElementAttributes() Retrieves A COPY OF the default element attributes used by this region.
IElementAttributes	getElementAttributes() Deprecated. As of release 1.3
IElementAttributes	getElementAttributes(java.lang.Object name) GetElementAttributes will return an attribute object describing the current attributes associated with the object name.
java.util.HashMap	getMatching(java.lang.String pattern) Retrieve matching objects from the cache region this instance provides access to.
java.util.Map	getMatchingCacheElements(java.lang.String pattern) Get multiple elements from the cache based on a set of cache keys.
ICacheStats	getStatistics() This returns the ICacheStats object with information on this region and its auxiliaries.
java.lang.String	getStats()
void	put(java.lang.Object name, java.lang.Object obj) Place a new object in the cache, associated with key name.
void	put(java.lang.Object key, java.lang.Object val, IElementAttributes attr) Constructs a cache element with these attributes, and puts it into the cache.
void	putSafe(java.lang.Object key, java.lang.Object value) Place a new object in the cache, associated with key name.
void	remove() Deprecated. use clear()
void	remove(java.lang.Object name) Removes a single item by name.
void	resetElementAttributes(IElementAttributes attr) Deprecated. As of release 1.3
void	resetElementAttributes(java.lang.Object name, IElementAttributes attr) Reset attributes for a particular element in the cache.
void	setCacheAttributes(ICompositeCacheAttributes cattr) Sets the ICompositeCacheAttributes of the cache region.
void	setDefaultElementAttributes(IElementAttributes attr) This method is does not reset the attributes for items already in the cache.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

cacheControl

protected CompositeCache cacheControl

The cache that a given instance of this class provides access to.

Constructor Detail

CacheAccess

public CacheAccess(CompositeCache cacheControl)

Constructor for the CacheAccess object.

Parameters:

cacheControl - The cache which the created instance accesses

Method Detail

defineRegion

public static CacheAccess defineRegion(java.lang.String name)
                                throws CacheException

Define a new cache region with the given name. In the oracle specification, these attributes are global and not region specific, regional overrides is a value add each region should be able to house both cache and element attribute sets. It is more efficient to define a cache in the props file and then strictly use the get access method. Use of the define region outside of an initialization block should be avoided.

Parameters:

name - Name that will identify the region

Returns:

CacheAccess instance for the new region

Throws:

CacheException

defineRegion

public static CacheAccess defineRegion(java.lang.String name,
                       ICompositeCacheAttributes cattr)
                                throws CacheException

Define a new cache region with the specified name and attributes.

Parameters:

name - Name that will identify the region

cattr - CompositeCacheAttributes for the region

Returns:

CacheAccess instance for the new region

Throws:

CacheException

defineRegion

public static CacheAccess defineRegion(java.lang.String name,
                       ICompositeCacheAttributes cattr,
                       IElementAttributes attr)
                                throws CacheException

Define a new cache region with the specified name and attributes and return a CacheAccess to it.

Parameters:

name - Name that will identify the region

cattr - CompositeCacheAttributes for the region

attr - Attributes for the region

Returns:

CacheAccess instance for the new region

Throws:

CacheException

getAccess

public static CacheAccess getAccess(java.lang.String region)
                             throws CacheException

Get a CacheAccess instance for the given region.

Parameters:

region - Name that identifies the region

Returns:

CacheAccess instance for region

Throws:

CacheException

getAccess

public static CacheAccess getAccess(java.lang.String region,
                    ICompositeCacheAttributes icca)
                             throws CacheException

Get a CacheAccess instance for the given region with the given attributes.

Parameters:

region - Name that identifies the region

icca -

Returns:

CacheAccess instance for region

Throws:

CacheException

ensureCacheManager

protected static void ensureCacheManager()

Helper method which checks to make sure the cacheMgr class field is set, and if not requests an instance from CacheManagerFactory.

get

public java.lang.Object get(java.lang.Object name)

Retrieve an object from the cache region this instance provides access to.

Specified by:

get in interface ICacheAccess

Parameters:

name - Key the object is stored as

Returns:

The object if found or null

getMatching

public java.util.HashMap getMatching(java.lang.String pattern)

Retrieve matching objects from the cache region this instance provides access to.

Specified by:

getMatching in interface ICacheAccess

Parameters:

pattern - - a key pattern for the objects stored

Returns:

A map of key to values. These are stripped from the wrapper.

getCacheElement

public ICacheElement getCacheElement(java.lang.Object name)

This method returns the ICacheElement wrapper which provides access to element info and other attributes.

This returns a reference to the wrapper. Any modifications will be reflected in the cache. No defensive copy is made.

This method is most useful if you want to determine things such as the how long the element has been in the cache.

The last access time in the ElementAttributes should be current.

Specified by:

getCacheElement in interface ICacheAccess

Parameters:

name - Key the object is stored as

Returns:

The ICacheElement if the object is found or null

getCacheElements

public java.util.Map getCacheElements(java.util.Set names)

Get multiple elements from the cache based on a set of cache keys.

This method returns the ICacheElement wrapper which provides access to element info and other attributes.

This returns a reference to the wrapper. Any modifications will be reflected in the cache. No defensive copy is made.

This method is most useful if you want to determine things such as the how long the element has been in the cache.

The last access time in the ElementAttributes should be current.

Specified by:

getCacheElements in interface ICacheAccess

Parameters:

names - set of Object cache keys

Returns:

a map of Object key to ICacheElement element, or empty map if none of the keys are present

getMatchingCacheElements

public java.util.Map getMatchingCacheElements(java.lang.String pattern)

Get multiple elements from the cache based on a set of cache keys.

This method returns the ICacheElement wrapper which provides access to element info and other attributes.

This returns a reference to the wrapper. Any modifications will be reflected in the cache. No defensive copy is made.

This method is most useful if you want to determine things such as the how long the element has been in the cache.

The last access time in the ElementAttributes should be current.

Specified by:

getMatchingCacheElements in interface ICacheAccess

Parameters:

pattern - key search pattern

Returns:

a map of Object key to ICacheElement element, or empty map if no keys match the pattern

putSafe

public void putSafe(java.lang.Object key,
           java.lang.Object value)
             throws CacheException

Place a new object in the cache, associated with key name. If there is currently an object associated with name in the region an ObjectExistsException is thrown. Names are scoped to a region so they must be unique within the region they are placed.

Specified by:

putSafe in interface ICacheAccess

Parameters:

key - Key object will be stored with

value - Object to store

Throws:

CacheException - and ObjectExistsException is thrown if the item is already in the cache.

put

public void put(java.lang.Object name,
       java.lang.Object obj)
         throws CacheException

Place a new object in the cache, associated with key name. If there is currently an object associated with name in the region it is replaced. Names are scoped to a region so they must be unique within the region they are placed. ObjectExistsException

Specified by:

put in interface ICacheAccess

Parameters:

name - Key object will be stored with

obj - Object to store

Throws:

CacheException

put

public void put(java.lang.Object key,
       java.lang.Object val,
       IElementAttributes attr)
         throws CacheException

Constructs a cache element with these attributes, and puts it into the cache.

If the key or the value is null, and InvalidArgumentException is thrown.

Specified by:

put in interface ICacheAccess

Throws:

CacheException

See Also:

ICacheAccess.put(java.lang.Object, java.lang.Object, org.apache.jcs.engine.behavior.IElementAttributes)

destroy

public void destroy()
             throws CacheException

Deprecated.

Destroy the region and all objects within it. After calling this method, the Cache object can no longer be used as it will be closed.

Specified by:

destroy in interface ICacheAccess

Throws:

CacheException

See Also:

ICacheAccess.remove()

remove

public void remove()
            throws CacheException

Deprecated. use clear()

Removes all of the elements from a region.

Specified by:

remove in interface ICacheAccess

Throws:

CacheException

clear

public void clear()
           throws CacheException

Removes all of the elements from a region.

Throws:

CacheException

destroy

public void destroy(java.lang.Object name)
             throws CacheException

Deprecated. use remove

Invalidate all objects associated with key name, removing all references to the objects from the cache.

Specified by:

destroy in interface ICacheAccess

Parameters:

name - Key that specifies object to invalidate

Throws:

CacheException

See Also:

ICacheAccess.remove(Object)

remove

public void remove(java.lang.Object name)
            throws CacheException

Removes a single item by name.

Specified by:

remove in interface ICacheAccess

Parameters:

name - the name of the item to remove.

Throws:

CacheException

resetElementAttributes

public void resetElementAttributes(IElementAttributes attr)
                            throws CacheException,
                                   InvalidHandleException

Deprecated. As of release 1.3

ResetAttributes allows for some of the attributes of a region to be reset in particular expiration time attributes, time to live, default time to live and idle time, and event handlers. Changing default settings on groups and regions will not affect existing objects. Only object loaded after the reset will use the new defaults. If no name argument is provided, the reset is applied to the region.

NOTE: this method is does not reset the attributes for items already in the cache. It could potentially do this for items in memory, and maybe on disk (which would be slow) but not remote items. Rather than have unpredictable behavior, this method just sets the default attributes.

TODO is should be renamed "setDefaultElementAttributes"

Specified by:

resetElementAttributes in interface ICacheAccess

Parameters:

attr - New attributes for this region.

Throws:

CacheException

InvalidHandleException

See Also:

setDefaultElementAttributes(IElementAttributes)

setDefaultElementAttributes

public void setDefaultElementAttributes(IElementAttributes attr)
                                 throws CacheException

This method is does not reset the attributes for items already in the cache. It could potentially do this for items in memory, and maybe on disk (which would be slow) but not remote items. Rather than have unpredictable behavior, this method just sets the default attributes. Items subsequently put into the cache will use these defaults if they do not specify specific attributes.

Parameters:

attr - the default attributes.

Throws:

CacheException - if something goes wrong.

resetElementAttributes

public void resetElementAttributes(java.lang.Object name,
                          IElementAttributes attr)
                            throws CacheException,
                                   InvalidHandleException

Reset attributes for a particular element in the cache. NOTE: this method is currently not implemented.

Specified by:

resetElementAttributes in interface ICacheAccess

Parameters:

name - Key of object to reset attributes for

attr - New attributes for the object

Throws:

CacheException

InvalidHandleException - if the item does not exist.

getElementAttributes

public IElementAttributes getElementAttributes()
                                        throws CacheException

Deprecated. As of release 1.3

GetElementAttributes will return an attribute object describing the current attributes associated with the object name.

This was confusing, so I created a new method with a clear name.

Specified by:

getElementAttributes in interface ICacheAccess

Returns:

Attributes for this region

Throws:

CacheException

See Also:

getDefaultElementAttributes()

getDefaultElementAttributes

public IElementAttributes getDefaultElementAttributes()
                                               throws CacheException

Retrieves A COPY OF the default element attributes used by this region. This does not provide a reference to the element attributes.

Each time an element is added to the cache without element attributes, the default element attributes are cloned.

Returns:

the deafualt element attributes used by this region.

Throws:

CacheException

getElementAttributes

public IElementAttributes getElementAttributes(java.lang.Object name)
                                        throws CacheException

GetElementAttributes will return an attribute object describing the current attributes associated with the object name. The name object must override the Object.equals and Object.hashCode methods.

Specified by:

getElementAttributes in interface ICacheAccess

Parameters:

name - Key of object to get attributes for

Returns:

Attributes for the object, null if object not in cache

Throws:

CacheException

getStatistics

public ICacheStats getStatistics()

This returns the ICacheStats object with information on this region and its auxiliaries.

This data can be formatted as needed.

Returns:

ICacheStats

getStats

public java.lang.String getStats()

Returns:

A String version of the stats.

dispose

public void dispose()

Dispose this region. Flushes objects to and closes auxiliary caches. This is a shutdown command!

To simply remove all elements from the region use clear().

getCacheAttributes

public ICompositeCacheAttributes getCacheAttributes()

Gets the ICompositeCacheAttributes of the cache region.

Specified by:

getCacheAttributes in interface ICacheAccess

Returns:

ICompositeCacheAttributes, the controllers config info, defined in the top section of a region definition.

setCacheAttributes

public void setCacheAttributes(ICompositeCacheAttributes cattr)

Sets the ICompositeCacheAttributes of the cache region.

Specified by:

setCacheAttributes in interface ICacheAccess

Parameters:

cattr - The new ICompositeCacheAttribute value

freeMemoryElements

public int freeMemoryElements(int numberToFree)
                       throws CacheException

This instructs the memory cache to remove the numberToFree according to its eviction policy. For example, the LRUMemoryCache will remove the numberToFree least recently used items. These will be spooled to disk if a disk auxiliary is available.

Specified by:

freeMemoryElements in interface ICacheAccess

Parameters:

numberToFree -

Returns:

the number that were removed. if you ask to free 5, but there are only 3, you will get 3.

Throws:

CacheException