You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@turbine.apache.org by jt...@apache.org on 2002/02/12 04:16:48 UTC
cvs commit: jakarta-turbine-stratum/src/java/org/apache/stratum/jcs/access CacheAccess.java GroupCacheAccess.java
jtaylor 02/02/11 19:16:48
Modified: src/java/org/apache/stratum/jcs/access CacheAccess.java
GroupCacheAccess.java
Log:
Cleaning up and adding javadoc to CacheAccess. I figured it would be worthwhile
to document as I dig through JCS. I also did a small refactoring and renamed
one instance field to better fit the naming conventions (cache_contol to
cacheControl). I'll try to do GroupCacheAccess tomorrow. Aaron, none of these
changes should be destructive, but I'm not clear on what the best way to test
JCS is. Please advise.
Revision Changes Path
1.6 +180 -217 jakarta-turbine-stratum/src/java/org/apache/stratum/jcs/access/CacheAccess.java
Index: CacheAccess.java
===================================================================
RCS file: /home/cvs/jakarta-turbine-stratum/src/java/org/apache/stratum/jcs/access/CacheAccess.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- CacheAccess.java 18 Jan 2002 15:38:15 -0000 1.5
+++ CacheAccess.java 12 Feb 2002 03:16:48 -0000 1.6
@@ -72,161 +72,132 @@
import org.apache.stratum.jcs.engine.control.CacheManagerFactory;
import org.apache.stratum.jcs.engine.control.CompositeCacheManager;
-// CACHE
-
-//////////////////////////////////////////////////////////////
/**
- * Description of the Class
+ * Class which provides interface for all access to the cache. An instance of
+ * this class is tied to a specific cache region. Static methods are provided
+ * to get such instances.
*
- *@author <a href="mailto:asmuts@yahoo.com">Aaron Smuts</a>
- *@created January 15, 2002
+ * @author <a href="mailto:asmuts@yahoo.com">Aaron Smuts</a>
+ * @version $Id: CacheAccess.java,v 1.6 2002/02/12 03:16:48 jtaylor Exp $
*/
public class CacheAccess implements ICacheAccess
{
-
+ /** Cache manager use by the various forms of defineRegion and getAccess */
private static CompositeCacheManager cacheMgr;
- /**
- * Description of the Field
- */
- protected Cache cache_control;
+ /** Cache that a given instance of this class provides access to */
+ protected Cache cacheControl;
- ////////////////////////////////////////////////
/**
- * Constructor for the CacheAccess object
+ * Constructor for the CacheAccess object.
*
- *@param cache_control Description of the Parameter
+ * @param cacheControl The cache which the created instance accesses
*/
- protected CacheAccess( Cache cache_control )
+ protected CacheAccess( Cache cacheControl )
{
- this.cache_control = cache_control;
+ this.cacheControl = cacheControl;
}
+ // ----------------------------- static methods for access to cache regions
- /////////////////////////////////////////
/**
- * 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.
+ * 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.
*
- *@param name Description of the Parameter
- *@return Description of the Return Value
- *@exception CacheException Description of the Exception
+ * @param name Name that will identify the region
+ * @return CacheAccess instance for the new region
+ * @exception CacheException
*/
public static CacheAccess defineRegion( String name )
throws CacheException
{
- if ( cacheMgr == null )
- {
- synchronized ( CacheAccess.class )
- {
- if ( cacheMgr == null )
- {
- cacheMgr = CacheManagerFactory.getInstance();
- }
- }
- }
- Cache cache_control = ( Cache ) cacheMgr.getCache( name );
- return new CacheAccess( cache_control );
+ ensureCacheManager();
+
+ return new CacheAccess( ( Cache ) cacheMgr.getCache( name ) );
}
-
- /////////////////////////////////////////
/**
- * Description of the Method
+ * Define a new cache region with the specified name and attributes.
*
- *@param name Description of the Parameter
- *@param cattr Description of the Parameter
- *@return Description of the Return Value
- *@exception CacheException Description of the Exception
+ * @param name Name that will identify the region
+ * @param cattr CompositeCacheAttributes for the region
+ * @return CacheAccess instance for the new region
+ * @exception CacheException
*/
- public static CacheAccess defineRegion( String name, CompositeCacheAttributes cattr )
+ public static CacheAccess defineRegion( String name,
+ CompositeCacheAttributes cattr )
throws CacheException
{
- if ( cacheMgr == null )
- {
- synchronized ( CacheAccess.class )
- {
- if ( cacheMgr == null )
- {
- cacheMgr = CacheManagerFactory.getInstance();
- }
- }
- }
- Cache cache_control = ( Cache ) cacheMgr.getCache( name, cattr );
- return new CacheAccess( cache_control );
+ ensureCacheManager();
+
+ return new CacheAccess( ( Cache ) cacheMgr.getCache( name, cattr ) );
}
-
- /////////////////////////////////////////
/**
- * Description of the Method
+ * Define a new cache region with the specified name and attributes.
*
- *@param name Description of the Parameter
- *@param cattr Description of the Parameter
- *@param attr Description of the Parameter
- *@return Description of the Return Value
- *@exception CacheException Description of the Exception
+ * @param name Name that will identify the region
+ * @param cattr CompositeCacheAttributes for the region
+ * @param attr Attributes for the region
+ * @return CacheAccess instance for the new region
+ * @exception CacheException
*/
- public static CacheAccess defineRegion( String name, CompositeCacheAttributes cattr, Attributes attr )
+ public static CacheAccess defineRegion( String name,
+ CompositeCacheAttributes cattr,
+ Attributes attr )
throws CacheException
{
- if ( cacheMgr == null )
- {
- synchronized ( CacheAccess.class )
- {
- if ( cacheMgr == null )
- {
- cacheMgr = CacheManagerFactory.getInstance();
- }
- }
- }
- Cache cache_control = ( Cache ) cacheMgr.getCache( name, cattr, attr );
- return new CacheAccess( cache_control );
+ ensureCacheManager();
+
+ return new CacheAccess(
+ ( Cache ) cacheMgr.getCache( name, cattr, attr ) );
}
-
- /////////////////////////////////////////
/**
- * Gets the access attribute of the CacheAccess class
+ * Get a CacheAccess instance for the given region.
*
- *@param region Description of the Parameter
- *@return The access value
- *@exception CacheException Description of the Exception
+ * @param region Name that identifies the region
+ * @return CacheAccess instance for region
+ * @exception CacheException
*/
public static CacheAccess getAccess( String region )
throws CacheException
{
- if ( cacheMgr == null )
- {
- synchronized ( CacheAccess.class )
- {
- if ( cacheMgr == null )
- {
- cacheMgr = CacheManagerFactory.getInstance();
- }
- }
- }
- Cache cache_control = ( Cache ) cacheMgr.getCache( region );
- return new CacheAccess( cache_control );
+ ensureCacheManager();
+
+ return new CacheAccess( ( Cache ) cacheMgr.getCache( region ) );
}
-
- /////////////////////////////////////////
/**
- * Gets the access attribute of the CacheAccess class
+ * Get a CacheAccess instance for the given region with the given
+ * attributes.
*
- *@param region Description of the Parameter
- *@param icca Description of the Parameter
- *@return The access value
- *@exception CacheException Description of the Exception
+ * @param region Name that identifies the region
+ * @param icca
+ * @return CacheAccess instance for region
+ * @exception CacheException
*/
- public static CacheAccess getAccess( String region, ICompositeCacheAttributes icca )
+ public static CacheAccess getAccess( String region,
+ ICompositeCacheAttributes icca )
throws CacheException
{
+ ensureCacheManager();
+
+ return new CacheAccess( ( Cache ) cacheMgr.getCache( region, icca ) );
+ }
+
+ /**
+ * Helper method which checks to make sure the cacheMgr class field is set,
+ * and if not requests an instance from CacheManagerFactory.
+ */
+ protected static void ensureCacheManager()
+ {
if ( cacheMgr == null )
{
synchronized ( CacheAccess.class )
@@ -237,43 +208,38 @@
}
}
}
- Cache cache_control = ( Cache ) cacheMgr.getCache( region, icca );
- return new CacheAccess( cache_control );
}
+
+ // ------------------------------------------------------- instance methods
-
- /////////////////////////////////////////
/**
- * Description of the Method
+ * Retrieve an object from the cache region this instance provides access
+ * to.
*
- *@param name Description of the Parameter
- *@return Description of the Return Value
+ * @param name Key the object is stored as
+ * @return The object if found or null
*/
public Object get( String name )
{
- return ( Object ) cache_control.get( ( Serializable ) name );
+ return ( Object ) cacheControl.get( ( Serializable ) name );
}
-
- /////////////////////////////////////////
/**
- * Put allows a new object to be placed into the cache identified by 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. Attributes to associate with the object may be
- * specified with attr. If attr is not supplied, default attributes are
- * assumed.
+ * 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.
*
- *@param name Description of the Parameter
- *@param obj Description of the Parameter
- *@exception CacheException Description of the Exception
+ * @param name Key object will be stored with
+ * @param obj Object to store
+ * @exception CacheException
*/
public void put( Object name, Object obj )
throws CacheException
{
try
{
- cache_control.put( ( Serializable ) name, ( Serializable ) obj );
+ cacheControl.put( ( Serializable ) name, ( Serializable ) obj );
}
catch ( Exception e )
{
@@ -281,21 +247,23 @@
}
}
-
/**
- * Description of the Method
+ * Place a new object in the cache. This form allows attributes to
+ * associate with the object may be specified with attr.
*
- *@param name Description of the Parameter
- *@param obj Description of the Parameter
- *@param attr Description of the Parameter
- *@exception CacheException Description of the Exception
+ * @param name Key object will be stored with
+ * @param obj Object to store
+ * @param attr Attributes to store object with
+ * @exception CacheException
*/
public void put( Object name, Object obj, Attributes attr )
throws CacheException
{
try
{
- cache_control.put( ( Serializable ) name, ( Serializable ) obj, attr );
+ cacheControl.put( ( Serializable ) name,
+ ( Serializable ) obj,
+ attr );
}
catch ( Exception e )
{
@@ -303,179 +271,174 @@
}
}
-
/**
- * Destroy will invalidate all objects associated with name removing all
- * references to the objects from the cache. If name is not specified, the
- * region and all objects within the region will be destroyed. If destroy
- * is called without a name attribute, the Cache object can no longer be
- * used as it will be closed.
+ * 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.
*
- *@exception CacheException Description of the Exception
+ * @exception CacheException
*/
public void destroy()
throws CacheException
{
- cache_control.removeAll();
+ cacheControl.removeAll();
}
-
/**
- * Description of the Method
+ * Invalidate all objects associated with key name, removing all references
+ * to the objects from the cache.
*
- *@param name Description of the Parameter
- *@exception CacheException Description of the Exception
+ * @param name Key that specifies object to invalidate
+ * @exception CacheException
*/
public void destroy( Object name )
throws CacheException
{
- cache_control.remove( ( Serializable ) name );
+ cacheControl.remove( ( Serializable ) name );
}
-
/**
- * Remove either the entire region of elements or the the specified element
- * from other caches specified in in the cache.properties file as lateral
- * caches.
+ * Remove the entire region of elements from other caches specified in the
+ * cache.properties file as lateral caches.
*/
public void removeLateralDirect()
{
- cache_control.removeLateralDirect( "ALL" );
- return;
+ cacheControl.removeLateralDirect( "ALL" );
}
-
/**
- * Description of the Method
+ * Remove the specified element from other caches specified in in the
+ * cache.properties file as lateral caches.
*
- *@param key Description of the Parameter
+ * @param key Key identifying object to remove
*/
public void removeLateralDirect( Serializable key )
{
- cache_control.removeLateralDirect( key );
- return;
+ cacheControl.removeLateralDirect( key );
}
-
- ///////////////////////////////////////
/**
- * Description of the Method
+ * If there are any auxiliary caches associated with this cache, save all
+ * objects to them.
*/
public void save()
{
- cache_control.save();
+ cacheControl.save();
}
-
/**
- * 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.
+ * 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.
*
- *@param attr Description of the Parameter
- *@exception CacheException Description of the Exception
- *@exception InvalidHandleException Description of the Exception
+ * NOTE: this method is currently not implemented.
+ *
+ * @param attr New attributes for this region.
+ * @exception CacheException
+ * @exception InvalidHandleException
*/
public void resetElementAttributes( Attributes attr )
- throws CacheException, InvalidHandleException { }
-
+ throws CacheException, InvalidHandleException
+ {
+ // Not implemented
+ }
/**
- * Description of the Method
+ * Reset attributes for a particular element in the cache.
+ *
+ * NOTE: this method is currently not implemented.
*
- *@param name Description of the Parameter
- *@param attr Description of the Parameter
- *@exception CacheException Description of the Exception
- *@exception InvalidHandleException Description of the Exception
+ * @param name Key of object to reset attributes for
+ * @param attr New attributes for the object
+ * @exception CacheException
+ * @exception InvalidHandleException
*/
public void resetElementAttributes( Object name, Attributes attr )
- throws CacheException, InvalidHandleException { }
-
+ throws CacheException, InvalidHandleException
+ {
+ // Not implemented
+ }
/**
- * GetAttributes will return an attribute object describing the current
- * attributes associated with the object name. If no name parameter is
- * available, the attributes for the region will be returned. The name
- * object must override the Object.equals and Object.hashCode methods.
+ * GetAttributes will return an attribute object describing the current
+ * attributes associated with the object name.
*
- *@return The elementAttributes value
- *@exception CacheException Description of the Exception
+ * @return Attributes for this region
+ * @exception CacheException
*/
public Attributes getElementAttributes()
throws CacheException
{
- return cache_control.attr;
+ return cacheControl.attr;
}
-
/**
- * Gets the elementAttributes attribute of the CacheAccess object
+ * GetAttributes 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.
*
- *@param name Description of the Parameter
- *@return The elementAttributes value
- *@exception CacheException Description of the Exception
+ * @param name Key of object to get attributes for
+ * @return Attributes for the object, null if object not in cache
+ * @exception CacheException
*/
public Attributes getElementAttributes( Object name )
throws CacheException
{
Attributes attr = null;
+
try
{
- attr = cache_control.getElementAttributes( ( Serializable ) name );
+ attr = cacheControl.getElementAttributes( ( Serializable ) name );
}
catch ( IOException ioe )
{
p( ioe.toString() );
}
+
return attr;
}
-
-// ///////////////////////////////////////////////////
-// // METHODS FOR TESTING AND ERROR REPORTING
-// protected void dumpMap() {
-// cache_control.dumpMap();
-// }
-//
-// ///////////////////////////////////////////////////
-// protected void dumpCacheEntries() {
-// cache_control.dumpCacheEntries();
-// }
-
- ////////////////////////////////////////////////////
/**
- * Description of the Method
+ * Dispose this region. Flushes objects to and closes auxiliary caches.
*/
protected void dispose()
{
- cache_control.dispose();
+ cacheControl.dispose();
}
-
- ////////////////////////////////////////////////////
/**
- * Gets the stats attribute of the CacheAccess object
+ * Return statistics for the region.
*
- *@return The stats value
+ * @return HTML formatted string containing region statistics
*/
protected String getStats()
{
- return cache_control.getStats();
+ return cacheControl.getStats();
}
-
- ////////////////////////////////////////////////////
/**
- * Description of the Method
+ * Wrapper to System.out.println
*
- *@param s Description of the Parameter
+ * FIXME: Replace (at call points) with logging mechanism.
+ *
+ * @param s String to print
*/
public static void p( String s )
{
System.out.println( s );
}
-
+
+ // -------------------------------- methods for testing and error reporting
+
+ // protected void dumpMap()
+ // {
+ // cache_control.dumpMap();
+ // }
+ //
+ // protected void dumpCacheEntries()
+ // {
+ // cache_control.dumpCacheEntries();
+ // }
}
1.8 +21 -23 jakarta-turbine-stratum/src/java/org/apache/stratum/jcs/access/GroupCacheAccess.java
Index: GroupCacheAccess.java
===================================================================
RCS file: /home/cvs/jakarta-turbine-stratum/src/java/org/apache/stratum/jcs/access/GroupCacheAccess.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- GroupCacheAccess.java 17 Jan 2002 00:19:37 -0000 1.7
+++ GroupCacheAccess.java 12 Feb 2002 03:16:48 -0000 1.8
@@ -99,19 +99,18 @@
private static GroupCacheManager cacheMgr;
- //private GroupCache cache_control;
+ //private GroupCache cacheControl;
///////////////////////////////////////////
/**
* Constructor for the GroupCacheAccess object
*
- *@param cache_control Description of the Parameter
+ *@param cacheControl Description of the Parameter
*/
- protected GroupCacheAccess( Cache cache_control )
+ protected GroupCacheAccess( Cache cacheControl )
{
- super( cache_control );
- //this.cache_control = cache_control;
+ super( cacheControl );
}
@@ -136,8 +135,7 @@
}
}
}
- Cache cache_control = ( Cache ) cacheMgr.getCache( region );
- return new GroupCacheAccess( cache_control );
+ return new GroupCacheAccess( ( Cache ) cacheMgr.getCache( region ) );
}
@@ -163,8 +161,8 @@
}
}
}
- Cache cache_control = ( Cache ) cacheMgr.getCache( region, icca );
- return new GroupCacheAccess( cache_control );
+
+ return new GroupCacheAccess( ( Cache ) cacheMgr.getCache( region, icca ) );
}
@@ -193,7 +191,7 @@
public Object getAttribute( String name, String group )
{
//try {
- return ( Object ) cache_control.get( new GroupAttrName( group, name ) );
+ return ( Object ) cacheControl.get( new GroupAttrName( group, name ) );
//} catch( ObjectNotFoundException onfe ) {
// return null;
//}
@@ -250,7 +248,7 @@
throws CacheException
{
// update the attribute name set.
- GroupId groupId = new GroupId( cache_control.getCacheName(), name );
+ GroupId groupId = new GroupId( cacheControl.getCacheName(), name );
HashSet attrNameSet = null;
//try {
attrNameSet = ( HashSet ) super.get( name );
@@ -266,7 +264,7 @@
}
try
{
- cache_control.put( ( Serializable ) groupId, ( Serializable ) attrNameSet );
+ cacheControl.put( ( Serializable ) groupId, ( Serializable ) attrNameSet );
}
catch ( Exception ioe )
{}
@@ -284,11 +282,11 @@
throws CacheException
{
// update the attribute name set.
- GroupId groupId = new GroupId( cache_control.getCacheName(), name );
+ GroupId groupId = new GroupId( cacheControl.getCacheName(), name );
HashSet attrNameSet = null;
//attrNameSet = (HashSet)super.get(name);
- attrNameSet = ( HashSet ) cache_control.get( groupId );
+ attrNameSet = ( HashSet ) cacheControl.get( groupId );
if ( attrNameSet == null )
{
@@ -300,10 +298,10 @@
}
try
{
- //cache_control.put((Serializable)groupId, (Serializable)attrNameSet, attr );
+ //cacheControl.put((Serializable)groupId, (Serializable)attrNameSet, attr );
// TODO: revisit and verify that this works
// not sure it will, need special id putting
- cache_control.put( groupId, ( Serializable ) attrNameSet, attr );
+ cacheControl.put( groupId, ( Serializable ) attrNameSet, attr );
}
catch ( Exception ioe )
{}
@@ -326,7 +324,7 @@
Attributes attr = null;
try
{
- attr = cache_control.getElementAttributes( ( Serializable ) name );
+ attr = cacheControl.getElementAttributes( ( Serializable ) name );
}
catch ( Exception ioe )
{
@@ -362,7 +360,7 @@
{
Object obj = null;
//try {
- obj = cache_control.get( new GroupId( cache_control.getCacheName(), ( String ) group_name ), false );
+ obj = cacheControl.get( new GroupId( cacheControl.getCacheName(), ( String ) group_name ), false );
//} catch( ObjectNotFoundException onfe ) {
// return null;
//}
@@ -388,7 +386,7 @@
removeAttribute( name, group, SET_ATTR_INVOCATION );
try
{
- cache_control.put( new GroupAttrName( group, name ), ( Serializable ) value );
+ cacheControl.put( new GroupAttrName( group, name ), ( Serializable ) value );
//} catch( ObjectExistsException onfe ) {
// return;
}
@@ -415,7 +413,7 @@
removeAttribute( name, group, SET_ATTR_INVOCATION );
try
{
- cache_control.put( new GroupAttrName( group, name ), ( Serializable ) value, attr );
+ cacheControl.put( new GroupAttrName( group, name ), ( Serializable ) value, attr );
}
catch ( Exception e )
{
@@ -454,7 +452,7 @@
// Needs to retrive the attribute so as to do object unbinding, if necessary.
Serializable val = null;
//try {
- val = cache_control.get( key );
+ val = cacheControl.get( key );
//} catch( ObjectNotFoundException onfe ) {
// return;
//}
@@ -466,7 +464,7 @@
if ( invocation == REMOVE_ATTR_INVOCATION )
{
// remove attribute - name set taken care of by the session cache.
- cache_control.remove( key );
+ cacheControl.remove( key );
}
return;
}
@@ -516,7 +514,7 @@
// }
// get into concurrent modificaiton problems here.
// could make the removal of the ID invalidate the list?
- cache_control.remove( new GroupId( cache_control.getCacheName(), group ), false );
+ cacheControl.remove( new GroupId( cacheControl.getCacheName(), group ), false );
return;
}
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>