org.apache.jcs.access
Class CacheAccess

java.lang.Object
  extended byorg.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 items wrapper, the element configuration, put an item in the cache, remove an item, and clear a region.

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

Version:
$Id: CacheAccess.java,v 1.20 2005/06/04 02:01:58 asmuts Exp $

Field Summary
protected  CompositeCache cacheControl
          The cache that a given instance of this class provides access to.
 
Constructor Summary
CacheAccess(CompositeCache cacheControl)
          Constructor for the CacheAccess object.
 
Method Summary
 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, CompositeCacheAttributes cattr)
          Define a new cache region with the specified name and attributes.
static CacheAccess defineRegion(java.lang.String name, CompositeCacheAttributes 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.
 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.
 IElementAttributes getElementAttributes()
          GetElementAttributes will return an attribute object describing the current attributes associated with the object name.
 IElementAttributes getElementAttributes(java.lang.Object name)
          GetElementAttributes will return an attribute object describing the current attributes associated with the object name.
 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)
          Description of the Method
 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)
          ResetAttributes allows for some of the attributes of a region to be reset in particular expiration time attriubtes, time to live, default time to live and idle time, and event handlers.
 void resetElementAttributes(java.lang.Object name, IElementAttributes attr)
          Reset attributes for a particular element in the cache.
 void save()
          If there are any auxiliary caches associated with this cache, save all objects to them.
 void setCacheAttributes(ICompositeCacheAttributes cattr)
          Sets the ICompositeCacheAttributes of the cache region.
 
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 overirdes 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,
                                       CompositeCacheAttributes 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,
                                       CompositeCacheAttributes 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

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 teh ElementAttributes should be current.

Parameters:
name - Key the object is stored as
Returns:
The ICacheElement if the object is found or null

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

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.

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
Description copied from interface: ICacheAccess
Description of the Method

Specified by:
put in interface ICacheAccess
Parameters:
key -
val -
attr -
Throws:
CacheException

destroy

public void destroy()
             throws CacheException
Deprecated.  

Destory 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()

remove

public void remove(java.lang.Object name)
            throws CacheException
Removes a single item by name.

Specified by:
remove in interface ICacheAccess
Parameters:
name -
Throws:
CacheException

save

public void save()
If there are any auxiliary caches associated with this cache, save all objects to them.

This is mainly a testing method. Dispose should do what you want on shutdown in a safer manner.


resetElementAttributes

public void resetElementAttributes(IElementAttributes attr)
                            throws CacheException,
                                   InvalidHandleException
ResetAttributes allows for some of the attributes of a region to be reset in particular expiration time attriubtes, 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 currently not implemented.

Specified by:
resetElementAttributes in interface ICacheAccess
Parameters:
attr - New attributes for this region.
Throws:
CacheException
InvalidHandleException

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

getElementAttributes

public IElementAttributes getElementAttributes()
                                        throws CacheException
GetElementAttributes will return an attribute object describing the current attributes associated with the object name.

Specified by:
getElementAttributes in interface ICacheAccess
Returns:
Attributes for 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


Copyright © 2002-2005 Apache Software Foundation. All Rights Reserved.