Think that a better named class (say JCSAccess) extending GroupCacheAccess, should be put in the root jcs package.
This would be the only package someone would have to import. > -----Original Message----- > From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED]] > Sent: Monday, February 11, 2002 10:17 PM > To: [EMAIL PROTECTED] > Subject: 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:[EMAIL PROTECTED]";>Aaron Smuts</a> > - *@created January 15, 2002 > + * @author <a href="mailto:[EMAIL PROTECTED]";>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: <mailto:turbine-dev- > [EMAIL PROTECTED]> > For additional commands, e-mail: <mailto:turbine-dev- > [EMAIL PROTECTED]>
