Coverage report

  %line %branch
org.apache.jcs.access.CacheAccess
75% 
94% 

 1  
 package org.apache.jcs.access;
 2  
 
 3  
 /*
 4  
  * Licensed to the Apache Software Foundation (ASF) under one
 5  
  * or more contributor license agreements.  See the NOTICE file
 6  
  * distributed with this work for additional information
 7  
  * regarding copyright ownership.  The ASF licenses this file
 8  
  * to you under the Apache License, Version 2.0 (the
 9  
  * "License"); you may not use this file except in compliance
 10  
  * with the License.  You may obtain a copy of the License at
 11  
  *
 12  
  *   http://www.apache.org/licenses/LICENSE-2.0
 13  
  *
 14  
  * Unless required by applicable law or agreed to in writing,
 15  
  * software distributed under the License is distributed on an
 16  
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 17  
  * KIND, either express or implied.  See the License for the
 18  
  * specific language governing permissions and limitations
 19  
  * under the License.
 20  
  */
 21  
 
 22  
 import java.io.IOException;
 23  
 import java.io.Serializable;
 24  
 
 25  
 import org.apache.commons.logging.Log;
 26  
 import org.apache.commons.logging.LogFactory;
 27  
 import org.apache.jcs.access.behavior.ICacheAccess;
 28  
 import org.apache.jcs.access.exception.CacheException;
 29  
 import org.apache.jcs.access.exception.InvalidArgumentException;
 30  
 import org.apache.jcs.access.exception.InvalidHandleException;
 31  
 import org.apache.jcs.access.exception.ObjectExistsException;
 32  
 import org.apache.jcs.engine.CacheElement;
 33  
 import org.apache.jcs.engine.behavior.ICacheElement;
 34  
 import org.apache.jcs.engine.behavior.ICompositeCacheAttributes;
 35  
 import org.apache.jcs.engine.behavior.IElementAttributes;
 36  
 import org.apache.jcs.engine.control.CompositeCache;
 37  
 import org.apache.jcs.engine.control.CompositeCacheManager;
 38  
 import org.apache.jcs.engine.stats.behavior.ICacheStats;
 39  
 
 40  
 /**
 41  
  * This class provides an interface for all types of access to the cache.
 42  
  * <p>
 43  
  * An instance of this class is tied to a specific cache region. Static methods are provided to get
 44  
  * such instances.
 45  
  * <p>
 46  
  * Using this class you can retrieve an item, the items wrapper, the element configuration, put an
 47  
  * item in the cache, remove an item, and clear a region.
 48  
  * <p>
 49  
  * The JCS class is the prefered way to access these methods.
 50  
  */
 51  6
 public class CacheAccess
 52  
     implements ICacheAccess
 53  
 {
 54  6
     /** The logger. */
 55  348
     private static final Log log = LogFactory.getLog( CacheAccess.class );
 56  
 
 57  
     /**
 58  
      * Cache manager use by the various forms of defineRegion and getAccess
 59  
      */
 60  
     private static CompositeCacheManager cacheMgr;
 61  
 
 62  
     /**
 63  
      * The cache that a given instance of this class provides access to.
 64  
      * <p>
 65  
      * @TODO Should this be the inteface?
 66  
      */
 67  
     protected CompositeCache cacheControl;
 68  
 
 69  
     /**
 70  
      * Constructor for the CacheAccess object.
 71  
      * <p>
 72  
      * @param cacheControl The cache which the created instance accesses
 73  
      */
 74  15
     public CacheAccess( CompositeCache cacheControl )
 75  645
     {
 76  665
         this.cacheControl = cacheControl;
 77  664
     }
 78  
 
 79  
     // ----------------------------- static methods for access to cache regions
 80  
 
 81  
     /**
 82  
      * Define a new cache region with the given name. In the oracle specification, these attributes
 83  
      * are global and not region specific, regional overirdes is a value add each region should be
 84  
      * able to house both cache and element attribute sets. It is more efficient to define a cache
 85  
      * in the props file and then strictly use the get access method. Use of the define region
 86  
      * outside of an initialization block should be avoided.
 87  
      * <p>
 88  
      * @param name Name that will identify the region
 89  
      * @return CacheAccess instance for the new region
 90  
      * @exception CacheException
 91  
      */
 92  
     public static CacheAccess defineRegion( String name )
 93  
         throws CacheException
 94  
     {
 95  8
         ensureCacheManager();
 96  
 
 97  8
         return new CacheAccess( cacheMgr.getCache( name ) );
 98  
     }
 99  
 
 100  
     /**
 101  
      * Define a new cache region with the specified name and attributes.
 102  
      * <p>
 103  
      * @param name Name that will identify the region
 104  
      * @param cattr CompositeCacheAttributes for the region
 105  
      * @return CacheAccess instance for the new region
 106  
      * @exception CacheException
 107  
      */
 108  
     public static CacheAccess defineRegion( String name, ICompositeCacheAttributes cattr )
 109  
         throws CacheException
 110  
     {
 111  8
         ensureCacheManager();
 112  
 
 113  8
         return new CacheAccess( cacheMgr.getCache( name, cattr ) );
 114  
     }
 115  
 
 116  
     /**
 117  
      * Define a new cache region with the specified name and attributes and return a CacheAccess to
 118  
      * it.
 119  
      * <p>
 120  
      * @param name Name that will identify the region
 121  
      * @param cattr CompositeCacheAttributes for the region
 122  
      * @param attr Attributes for the region
 123  
      * @return CacheAccess instance for the new region
 124  
      * @exception CacheException
 125  
      */
 126  
     public static CacheAccess defineRegion( String name, ICompositeCacheAttributes cattr, IElementAttributes attr )
 127  
         throws CacheException
 128  
     {
 129  8
         ensureCacheManager();
 130  
 
 131  8
         return new CacheAccess( cacheMgr.getCache( name, cattr, attr ) );
 132  
     }
 133  
 
 134  
     /**
 135  
      * Get a CacheAccess instance for the given region.
 136  
      * <p>
 137  
      * @param region Name that identifies the region
 138  
      * @return CacheAccess instance for region
 139  
      * @exception CacheException
 140  
      */
 141  
     public static CacheAccess getAccess( String region )
 142  
         throws CacheException
 143  
     {
 144  32
         ensureCacheManager();
 145  
 
 146  32
         return new CacheAccess( cacheMgr.getCache( region ) );
 147  
     }
 148  
 
 149  
     /**
 150  
      * Get a CacheAccess instance for the given region with the given attributes.
 151  
      * <p>
 152  
      * @param region Name that identifies the region
 153  
      * @param icca
 154  
      * @return CacheAccess instance for region
 155  
      * @exception CacheException
 156  
      */
 157  
     public static CacheAccess getAccess( String region, ICompositeCacheAttributes icca )
 158  
         throws CacheException
 159  
     {
 160  0
         ensureCacheManager();
 161  
 
 162  0
         return new CacheAccess( cacheMgr.getCache( region, icca ) );
 163  
     }
 164  
 
 165  
     /**
 166  
      * Helper method which checks to make sure the cacheMgr class field is set, and if not requests
 167  
      * an instance from CacheManagerFactory.
 168  
      */
 169  
     protected static void ensureCacheManager()
 170  
     {
 171  56
         synchronized ( CacheAccess.class )
 172  
         {
 173  56
             if ( cacheMgr == null )
 174  
             {
 175  8
                 cacheMgr = CompositeCacheManager.getInstance();
 176  
             }
 177  56
         }
 178  56
     }
 179  
 
 180  
     // ------------------------------------------------------- instance methods
 181  
 
 182  
     /**
 183  
      * Retrieve an object from the cache region this instance provides access to.
 184  
      * <p>
 185  
      * @param name Key the object is stored as
 186  
      * @return The object if found or null
 187  
      */
 188  
     public Object get( Object name )
 189  
     {
 190  1505649
         ICacheElement element = this.cacheControl.get( (Serializable) name );
 191  
 
 192  1506218
         return ( element != null ) ? element.getVal() : class="keyword">null;
 193  
     }
 194  
 
 195  
     /**
 196  
      * This method returns the ICacheElement wrapper which provides access to element info and other
 197  
      * attributes.
 198  
      * <p>
 199  
      * This returns a reference to the wrapper. Any modifications will be reflected in the cache. No
 200  
      * defensive copy is made.
 201  
      * <p>
 202  
      * This method is most useful if you want to determine things such as the how long the element
 203  67006
      * has been in the cache.
 204  
      * <p>
 205  67006
      * The last access time in teh ElementAttributes should be current.
 206  
      * <p>
 207  
      * @param name Key the object is stored as
 208  
      * @return The ICacheElement if the object is found or null
 209  
      */
 210  
     public ICacheElement getCacheElement( Object name )
 211  
     {
 212  15
         return this.cacheControl.get( (Serializable) name );
 213  
     }
 214  
 
 215  
     /**
 216  
      * Place a new object in the cache, associated with key name. If there is currently an object
 217  
      * associated with name in the region an ObjectExistsException is thrown. Names are scoped to a
 218  
      * region so they must be unique within the region they are placed.
 219  
      * <p>
 220  
      * @param key Key object will be stored with
 221  
      * @param value Object to store
 222  
      * @exception CacheException and ObjectExistsException is thrown if the item is already in the
 223  
      *                cache.
 224  
      */
 225  
     public void putSafe( Object key, Object value )
 226  1
         throws CacheException
 227  
     {
 228  8
         if ( this.cacheControl.get( (Serializable) key ) != null )
 229  
         {
 230  8
             throw new ObjectExistsException( "putSafe failed.  Object exists in the cache for key [" + key
 231  
                 + "].  Remove first or use a non-safe put to override the value." );
 232  
         }
 233  0
         put( key, value );
 234  0
     }
 235  
 
 236  
     /**
 237  
      * Place a new object in the cache, associated with key name. If there is currently an object
 238  
      * associated with name in the region it is replaced. Names are scoped to a region so they must
 239  
      * be unique within the region they are placed. ObjectExistsException
 240  
      * @param name Key object will be stored with
 241  
      * @param obj Object to store
 242  
      * @exception CacheException
 243  
      */
 244  
     public void put( Object name, Object obj )
 245  
         throws CacheException
 246  
     {
 247  
         // Call put with a copy of the contained caches default attributes.
 248  
         // the attributes are copied by the cacheControl
 249  1472240
         put( name, obj, this.cacheControl.getElementAttributes() );
 250  1472200
     }
 251  
 
 252  
     /**
 253  
      * Constructs a cache element with these attribures, and puts it into the cache.
 254  
      * <p>
 255  
      * If the key or the value is null, and InvalidArgumentException is thrown.
 256  
      * <p>
 257  
      * @see org.apache.jcs.access.behavior.ICacheAccess#put(java.lang.Object, java.lang.Object,
 258  
      *      org.apache.jcs.engine.behavior.IElementAttributes)
 259  
      */
 260  
     public void put( Object key, Object val, IElementAttributes attr )
 261  
         throws CacheException
 262  
     {
 263  1612299
         if ( key == null )
 264  
         {
 265  8
             throw new InvalidArgumentException( "Key must not be null" );
 266  
         }
 267  1612271
         else if ( val == null )
 268  
         {
 269  8
             throw new InvalidArgumentException( "Value must not be null" );
 270  72505
         }
 271  72505
 
 272  
         // Create the element and update. This may throw an IOException which
 273  
         // should be wrapped by cache access.
 274  
         try
 275  
         {
 276  1612282
             CacheElement ce = new CacheElement( this.cacheControl.getCacheName(), (Serializable) key,
 277  
                                                 (Serializable) val );
 278  
 
 279  1612104
             ce.setElementAttributes( attr );
 280  
 
 281  1612183
             this.cacheControl.update( ce );
 282  
         }
 283  1
         catch ( Exception e )
 284  
         {
 285  72506
             throw new CacheException( e );
 286  1612064
         }
 287  1612107
     }
 288  
 
 289  72505
     /**
 290  
      * Destory the region and all objects within it. After calling this method, the Cache object can
 291  
      * no longer be used as it will be closed.
 292  
      * <p>
 293  
      * @exception CacheException
 294  
      * @deprecated
 295  
      */
 296  
     public void destroy()
 297  
         throws CacheException
 298  145010
     {
 299  72505
         try
 300  
         {
 301  72505
             this.cacheControl.removeAll();
 302  
         }
 303  72505
         catch ( IOException e )
 304  
         {
 305  0
             throw new CacheException( e );
 306  0
         }
 307  0
     }
 308  
 
 309  72505
     /**
 310  
      * Removes all of the elements from a region.
 311  
      * <p>
 312  
      * @deprecated use clear()
 313  
      * @throws CacheException
 314  
      */
 315  
     public void remove()
 316  
         throws CacheException
 317  
     {
 318  0
         clear();
 319  0
     }
 320  
 
 321  
     /**
 322  
      * Removes all of the elements from a region.
 323  
      * <p>
 324  
      * @throws CacheException
 325  
      */
 326  
     public void clear()
 327  
         throws CacheException
 328  
     {
 329  
         try
 330  
         {
 331  79
             this.cacheControl.removeAll();
 332  
         }
 333  0
         catch ( IOException e )
 334  
         {
 335  0
             throw new CacheException( e );
 336  79
         }
 337  79
     }
 338  
 
 339  
     /**
 340  
      * Invalidate all objects associated with key name, removing all references to the objects from
 341  
      * the cache.
 342  
      * <p>
 343  
      * @param name Key that specifies object to invalidate
 344  
      * @exception CacheException
 345  
      * @deprecated use remove
 346  
      */
 347  
     public void destroy( Object name )
 348  
         throws CacheException
 349  
     {
 350  0
         this.cacheControl.remove( (Serializable) name );
 351  0
     }
 352  
 
 353  1
     /**
 354  
      * Removes a single item by name.
 355  
      * <p>
 356  
      * @param name the name of the item to remove.
 357  
      * @throws CacheException
 358  
      */
 359  1
     public void remove( Object name )
 360  
         throws CacheException
 361  
     {
 362  424363
         this.cacheControl.remove( (Serializable) name );
 363  424367
     }
 364  
 
 365  
     /**
 366  
      * ResetAttributes allows for some of the attributes of a region to be reset in particular
 367  
      * expiration time attriubtes, time to live, default time to live and idle time, and event
 368  
      * handlers. Changing default settings on groups and regions will not affect existing objects.
 369  
      * Only object loaded after the reset will use the new defaults. If no name argument is
 370  
      * provided, the reset is applied to the region.
 371  
      * <p>
 372  
      * NOTE: this method is does not reset the attributes for items already in the cache. It could
 373  
      * potentially do this for items in memory, and maybe on disk (which would be slow) but not
 374  
      * remote items. Rather than have unpredicatble behavior, this method just sets the default
 375  
      * attributes.
 376  
      * <p>
 377  
      * TODO is should be renamed "setDefaultElementAttributes"
 378  
      * <p>
 379  
      * @deprecated As of release 1.3
 380  
      * @see setDefaultElementAttributes
 381  
      * @param attr New attributes for this region.
 382  
      * @exception CacheException
 383  
      * @exception InvalidHandleException
 384  
      */
 385  
     public void resetElementAttributes( IElementAttributes attr )
 386  2003
         throws CacheException, InvalidHandleException
 387  2003
     {
 388  0
         this.cacheControl.setElementAttributes( attr );
 389  0
     }
 390  
 
 391  
     /**
 392  
      * This method is does not reset the attributes for items already in the cache. It could
 393  
      * potentially do this for items in memory, and maybe on disk (which would be slow) but not
 394  
      * remote items. Rather than have unpredicatble behavior, this method just sets the default
 395  
      * attributes. Items subsequently put into the cache will use these defaults if they do not
 396  
      * specify specific attributes.
 397  
      * <p>
 398  
      * @param attr the default attributes.
 399  
      * @throws CacheException if something goes wrong.
 400  
      */
 401  
     public void setDefaultElementAttributes( IElementAttributes attr )
 402  
         throws CacheException
 403  
     {
 404  29
         this.cacheControl.setElementAttributes( attr );
 405  29
     }
 406  
 
 407  
     /**
 408  
      * Reset attributes for a particular element in the cache. NOTE: this method is currently not
 409  
      * implemented.
 410  
      * <p>
 411  
      * @param name Key of object to reset attributes for
 412  
      * @param attr New attributes for the object
 413  
      * @exception CacheException
 414  
      * @exception InvalidHandleException if the item does not exist.
 415  
      */
 416  
     public void resetElementAttributes( Object name, IElementAttributes attr )
 417  
         throws CacheException, InvalidHandleException
 418  
     {
 419  0
         ICacheElement element = this.cacheControl.get( (Serializable) name );
 420  0
         if ( element == null )
 421  
         {
 422  0
             throw new InvalidHandleException( "Object for name [" + name + "] is not in the cache" );
 423  
         }
 424  
 
 425  
         // Although it will work currently, don't assume pass by reference here,
 426  
         // i.e. don't do this:
 427  
         // element.setElementAttributes( attr );
 428  
         // Another reason to call put is to force the changes to be distributed.
 429  0
         put( element.getKey(), element.getVal(), attr );
 430  
 
 431  0
     }
 432  
 
 433  
     /**
 434  
      * GetElementAttributes will return an attribute object describing the current attributes
 435  
      * associated with the object name.
 436  
      * <p>
 437  
      * This was confusing, so I created a new method with a clear name.
 438  
      * <p>
 439  
      * @deprecated As of release 1.3
 440  
      * @see getDefaultElementAttributes
 441  
      * @return Attributes for this region
 442  
      * @exception CacheException
 443  
      */
 444  
     public IElementAttributes getElementAttributes()
 445  
         throws CacheException
 446  
     {
 447  0
         return this.cacheControl.getElementAttributes();
 448  
     }
 449  
 
 450  
     /**
 451  
      * Retrieves A COPY OF the default element attributes used by this region. This does not provide
 452  
      * a reference to the element attributes.
 453  
      * <p>
 454  
      * Each time an element is added to the cache without element attributes, the default element
 455  
      * attributes are cloned.
 456  
      * <p>
 457  
      * @return the deafualt element attributes used by this region.
 458  
      * @throws CacheException
 459  
      */
 460  
     public IElementAttributes getDefaultElementAttributes()
 461  
         throws CacheException
 462  
     {
 463  140036
         return this.cacheControl.getElementAttributes();
 464  
     }
 465  
 
 466  
     /**
 467  
      * GetElementAttributes will return an attribute object describing the current attributes
 468  
      * associated with the object name. The name object must override the Object.equals and
 469  
      * Object.hashCode methods.
 470  
      * <p>
 471  
      * @param name Key of object to get attributes for
 472  
      * @return Attributes for the object, null if object not in cache
 473  
      * @exception CacheException
 474  
      */
 475  
     public IElementAttributes getElementAttributes( Object name )
 476  
         throws CacheException
 477  
     {
 478  0
         IElementAttributes attr = null;
 479  
 
 480  
         try
 481  
         {
 482  0
             attr = this.cacheControl.getElementAttributes( (Serializable) name );
 483  
         }
 484  0
         catch ( IOException ioe )
 485  
         {
 486  0
             log.error( "Failure getting element attributes", ioe );
 487  0
         }
 488  
 
 489  0
         return attr;
 490  
     }
 491  
 
 492  
     /**
 493  
      * This returns the ICacheStats object with information on this region and its auxiliaries.
 494  
      * <p>
 495  
      * This data can be formatted as needed.
 496  
      * <p>
 497  
      * @return ICacheStats
 498  
      */
 499  
     public ICacheStats getStatistics()
 500  
     {
 501  0
         return this.cacheControl.getStatistics();
 502  
     }
 503  
 
 504  
     /**
 505  
      * @return A String version of the stats.
 506  
      */
 507  
     public String getStats()
 508  
     {
 509  55690
         return this.cacheControl.getStats();
 510  
     }
 511  
 
 512  
     /**
 513  
      * Dispose this region. Flushes objects to and closes auxiliary caches. This is a shutdown
 514  
      * command!
 515  
      * <p>
 516  
      * To simply remove all elements from the region use clear().
 517  
      */
 518  
     public void dispose()
 519  
     {
 520  0
         this.cacheControl.dispose();
 521  0
     }
 522  
 
 523  
     /**
 524  
      * Gets the ICompositeCacheAttributes of the cache region.
 525  
      * <p>
 526  
      * @return ICompositeCacheAttributes, the controllers config info, defined in the top section of
 527  
      *         a region definition.
 528  
      */
 529  
     public ICompositeCacheAttributes getCacheAttributes()
 530  
     {
 531  109
         return this.cacheControl.getCacheAttributes();
 532  
     }
 533  
 
 534  
     /**
 535  
      * Sets the ICompositeCacheAttributes of the cache region.
 536  
      * <p>
 537  
      * @param cattr The new ICompositeCacheAttribute value
 538  
      */
 539  
     public void setCacheAttributes( ICompositeCacheAttributes cattr )
 540  
     {
 541  0
         this.cacheControl.setCacheAttributes( cattr );
 542  0
     }
 543  2
 
 544  
     /**
 545  
      * This instructs the memory cache to remove the <i>numberToFree</i> according to its eviction
 546  
      * policy. For example, the LRUMemoryCache will remove the <i>numberToFree</i> least recently
 547  
      * used items. These will be spooled to disk if a disk auxiliary is available.
 548  
      * <p>
 549  
      * @param numberToFree
 550  
      * @return the number that were removed. if you ask to free 5, but there are only 3, you will
 551  
      *         get 3.
 552  
      * @throws CacheException
 553  
      */
 554  
     public int freeMemoryElements( class="keyword">int numberToFree )
 555  
         throws CacheException
 556  
     {
 557  0
         int numFreed = -1;
 558  
         try
 559  
         {
 560  0
             numFreed = this.cacheControl.getMemoryCache().freeElements( numberToFree );
 561  
         }
 562  0
         catch ( IOException ioe )
 563  
         {
 564  0
             String message = "Failure freeing memory elements.  ";
 565  9
             log.error( message, ioe );
 566  0
             throw new CacheException( message + ioe.getMessage() );
 567  0
         }
 568  0
         return numFreed;
 569  
     }
 570  
 }

This report is generated by jcoverage, Maven and Maven JCoverage Plugin.