Clover coverage report -
Coverage timestamp: Sat Feb 28 2004 21:40:56 EST
file stats: LOC: 308   Methods: 19
NCLOC: 76   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
GeneralCacheAdministrator.java 100% 70.4% 63.2% 68.8%
coverage coverage
 1   
 /*
 2   
  * Copyright (c) 2002-2003 by OpenSymphony
 3   
  * All rights reserved.
 4   
  */
 5   
 package com.opensymphony.oscache.general;
 6   
 
 7   
 import com.opensymphony.oscache.base.*;
 8   
 
 9   
 import org.apache.commons.logging.Log;
 10   
 import org.apache.commons.logging.LogFactory;
 11   
 
 12   
 import java.util.Date;
 13   
 import java.util.Properties;
 14   
 
 15   
 /**
 16   
  * A GeneralCacheAdministrator creates, flushes and administers the cache.
 17   
  *
 18   
  * EXAMPLES :
 19   
  * <pre><code>
 20   
  * // ---------------------------------------------------------------
 21   
  * // Typical use with fail over
 22   
  * // ---------------------------------------------------------------
 23   
  * String myKey = "myKey";
 24   
  * String myValue;
 25   
  * int myRefreshPeriod = 1000;
 26   
  * try {
 27   
  *     // Get from the cache
 28   
  *     myValue = (String) admin.getFromCache(myKey, myRefreshPeriod);
 29   
  * } catch (NeedsRefreshException nre) {
 30   
  *     try {
 31   
  *         // Get the value (probably by calling an EJB)
 32   
  *         myValue = "This is the content retrieved.";
 33   
  *         // Store in the cache
 34   
  *         admin.putInCache(myKey, myValue);
 35   
  *     } catch (Exception ex) {
 36   
  *         // We have the current content if we want fail-over.
 37   
  *         myValue = (String) nre.getCacheContent();
 38   
  *         // It is essential that cancelUpdate is called if the
 39   
  *         // cached content is not rebuilt
 40   
  *         admin.cancelUpdate(myKey);
 41   
  *     }
 42   
  * }
 43   
  *
 44   
  *
 45   
  *
 46   
  * // ---------------------------------------------------------------
 47   
  * // Typical use without fail over
 48   
  * // ---------------------------------------------------------------
 49   
  * String myKey = "myKey";
 50   
  * String myValue;
 51   
  * int myRefreshPeriod = 1000;
 52   
  * try {
 53   
  *     // Get from the cache
 54   
  *     myValue = (String) admin.getFromCache(myKey, myRefreshPeriod);
 55   
  * } catch (NeedsRefreshException nre) {
 56   
  *     try {
 57   
  *         // Get the value (probably by calling an EJB)
 58   
  *         myValue = "This is the content retrieved.";
 59   
  *         // Store in the cache
 60   
  *         admin.putInCache(myKey, myValue);
 61   
  *         updated = true;
 62   
  *     } finally {
 63   
  *         if (!updated) {
 64   
  *             // It is essential that cancelUpdate is called if the
 65   
  *             // cached content could not be rebuilt
 66   
  *             admin.cancelUpdate(myKey);
 67   
  *         }
 68   
  *     }
 69   
  * }
 70   
  * // ---------------------------------------------------------------
 71   
  * // ---------------------------------------------------------------
 72   
  * </code></pre>
 73   
  *
 74   
  * @version        $Revision: 1.7 $
 75   
  * @author <a href="mailto:fbeauregard@pyxis-tech.com">Francois Beauregard</a>
 76   
  * @author <a href="mailto:abergevin@pyxis-tech.com">Alain Bergevin</a>
 77   
  */
 78   
 public class GeneralCacheAdministrator extends AbstractCacheAdministrator {
 79   
     private static transient final Log log = LogFactory.getLog(GeneralCacheAdministrator.class);
 80   
 
 81   
     /**
 82   
      * Application cache
 83   
      */
 84   
     private Cache applicationCache = null;
 85   
 
 86   
     /**
 87   
      * Create the cache administrator.
 88   
      */
 89  51
     public GeneralCacheAdministrator() {
 90  51
         this(null);
 91   
     }
 92   
 
 93   
     /**
 94   
      * Create the cache administrator with the specified properties
 95   
      */
 96  54
     public GeneralCacheAdministrator(Properties p) {
 97  54
         super(p);
 98  54
         log.info("Constructed GeneralCacheAdministrator()");
 99   
     }
 100   
 
 101   
     /**
 102   
      * Grabs a cache
 103   
      *
 104   
      * @return The cache
 105   
      */
 106  9911
     public Cache getCache() {
 107   
         // Create the cache if it doesn't already exist
 108  9819
         if (applicationCache == null) {
 109  45
             applicationCache = createCache();
 110   
         }
 111   
 
 112  9911
         return applicationCache;
 113   
     }
 114   
 
 115   
     /**
 116   
      * Get an object from the cache
 117   
      *
 118   
      * @param key             The key entered by the user.
 119   
      * @return   The object from cache
 120   
      * @throws NeedsRefreshException when no cache entry could be found with the
 121   
      * supplied key, or when an entry was found but is considered out of date. If
 122   
      * the cache entry is a new entry that is currently being constructed this method
 123   
      * will block until the new entry becomes available. Similarly, it will block if
 124   
      * a stale entry is currently being rebuilt by another thread and cache blocking is
 125   
      * enabled (<code>cache.blocking=true</code>).
 126   
      */
 127  0
     public Object getFromCache(String key) throws NeedsRefreshException {
 128  0
         return getCache().getFromCache(key);
 129   
     }
 130   
 
 131   
     /**
 132   
      * Get an object from the cache
 133   
      *
 134   
      * @param key             The key entered by the user.
 135   
      * @param refreshPeriod   How long the object can stay in cache in seconds. To
 136   
      * allow the entry to stay in the cache indefinitely, supply a value of
 137   
      * {@link CacheEntry#INDEFINITE_EXPIRY}
 138   
      * @return   The object from cache
 139   
      * @throws NeedsRefreshException when no cache entry could be found with the
 140   
      * supplied key, or when an entry was found but is considered out of date. If
 141   
      * the cache entry is a new entry that is currently being constructed this method
 142   
      * will block until the new entry becomes available. Similarly, it will block if
 143   
      * a stale entry is currently being rebuilt by another thread and cache blocking is
 144   
      * enabled (<code>cache.blocking=true</code>).
 145   
      */
 146  4680
     public Object getFromCache(String key, int refreshPeriod) throws NeedsRefreshException {
 147  4680
         return getCache().getFromCache(key, refreshPeriod);
 148   
     }
 149   
 
 150   
     /**
 151   
      * Get an object from the cache
 152   
      *
 153   
      * @param key             The key entered by the user.
 154   
      * @param refreshPeriod   How long the object can stay in cache in seconds. To
 155   
      * allow the entry to stay in the cache indefinitely, supply a value of
 156   
      * {@link CacheEntry#INDEFINITE_EXPIRY}
 157   
      * @param cronExpression  A cron expression that the age of the cache entry
 158   
      * will be compared to. If the entry is older than the most recent match for the
 159   
      * cron expression, the entry will be considered stale.
 160   
      * @return   The object from cache
 161   
      * @throws NeedsRefreshException when no cache entry could be found with the
 162   
      * supplied key, or when an entry was found but is considered out of date. If
 163   
      * the cache entry is a new entry that is currently being constructed this method
 164   
      * will block until the new entry becomes available. Similarly, it will block if
 165   
      * a stale entry is currently being rebuilt by another thread and cache blocking is
 166   
      * enabled (<code>cache.blocking=true</code>).
 167   
      */
 168  0
     public Object getFromCache(String key, int refreshPeriod, String cronExpression) throws NeedsRefreshException {
 169  0
         return getCache().getFromCache(key, refreshPeriod, cronExpression);
 170   
     }
 171   
 
 172   
     /**
 173   
      * Cancels a pending cache update. This should only be called by a thread
 174   
      * that received a {@link NeedsRefreshException} and was unable to generate
 175   
      * some new cache content.
 176   
      *
 177   
      * @param key The cache entry key to cancel the update of.
 178   
      */
 179  75
     public void cancelUpdate(String key) {
 180  75
         getCache().cancelUpdate(key);
 181   
     }
 182   
 
 183   
     /**
 184   
      * Shuts down the cache administrator.
 185   
      */
 186  3
     public void destroy() {
 187  3
         finalizeListeners(applicationCache);
 188   
     }
 189   
 
 190   
     // METHODS THAT DELEGATES TO THE CACHE ---------------------
 191   
 
 192   
     /**
 193   
      * Flush the entire cache immediately.
 194   
      */
 195  0
     public void flushAll() {
 196  0
         getCache().flushAll(new Date());
 197   
     }
 198   
 
 199   
     /**
 200   
      * Flush the entire cache at the given date.
 201   
      *
 202   
      * @param date The time to flush
 203   
      */
 204  0
     public void flushAll(Date date) {
 205  0
         getCache().flushAll(date);
 206   
     }
 207   
 
 208   
     /**
 209   
      * Flushes a single cache entry.
 210   
      */
 211  0
     public void flushEntry(String key) {
 212  0
         getCache().flushEntry(key);
 213   
     }
 214   
 
 215   
     /**
 216   
      * Flushes all items that belong to the specified group.
 217   
      *
 218   
      * @param group The name of the group to flush
 219   
      */
 220  24
     public void flushGroup(String group) {
 221  24
         getCache().flushGroup(group);
 222   
     }
 223   
 
 224   
     /**
 225   
      * Allows to flush all items that have a specified pattern in the key.
 226   
      *
 227   
      * @param pattern     Pattern.
 228   
      * @deprecated For performance and flexibility reasons it is preferable to
 229   
      * store cache entries in groups and use the {@link #flushGroup(String)} method
 230   
      * instead of relying on pattern flushing.
 231   
      */
 232  18
     public void flushPattern(String pattern) {
 233  18
         getCache().flushPattern(pattern);
 234   
     }
 235   
 
 236   
     /**
 237   
      * Put an object in a cache
 238   
      *
 239   
      * @param key       The key entered by the user
 240   
      * @param content   The object to store
 241   
      * @param policy    Object that implements refresh policy logic
 242   
      */
 243  4553
     public void putInCache(String key, Object content, EntryRefreshPolicy policy) {
 244  4553
         Cache cache = getCache();
 245  4553
         cache.putInCache(key, content, policy);
 246   
     }
 247   
 
 248   
     /**
 249   
      * Put an object in a cache
 250   
      *
 251   
      * @param key       The key entered by the user
 252   
      * @param content   The object to store
 253   
      */
 254  4550
     public void putInCache(String key, Object content) {
 255  4550
         putInCache(key, content, (EntryRefreshPolicy) null);
 256   
     }
 257   
 
 258   
     /**
 259   
      * Puts an object in a cache
 260   
      *
 261   
      * @param key      The unique key for this cached object
 262   
      * @param content  The object to store
 263   
      * @param groups   The groups that this object belongs to
 264   
      */
 265  54
     public void putInCache(String key, Object content, String[] groups) {
 266  54
         getCache().putInCache(key, content, groups);
 267   
     }
 268   
 
 269   
     /**
 270   
      * Puts an object in a cache
 271   
      *
 272   
      * @param key      The unique key for this cached object
 273   
      * @param content  The object to store
 274   
      * @param groups   The groups that this object belongs to
 275   
      * @param policy   The refresh policy to use
 276   
      */
 277  0
     public void putInCache(String key, Object content, String[] groups, EntryRefreshPolicy policy) {
 278  0
         getCache().putInCache(key, content, groups, policy, null);
 279   
     }
 280   
 
 281   
     /**
 282   
      * Sets the cache capacity (number of items). If the cache contains
 283   
      * more than <code>capacity</code> items then items will be removed
 284   
      * to bring the cache back down to the new size.
 285   
      *
 286   
      * @param capacity The new capacity of the cache
 287   
      */
 288  0
     public void setCacheCapacity(int capacity) {
 289  0
         super.setCacheCapacity(capacity);
 290  0
         getCache().setCapacity(capacity);
 291   
     }
 292   
 
 293   
     /**
 294   
      * Creates a cache in this admin
 295   
      *
 296   
      * @return The new cache
 297   
      */
 298  45
     private Cache createCache() {
 299  45
         log.info("Creating new cache");
 300   
 
 301  45
         Cache newCache = new Cache(isMemoryCaching(), isUnlimitedDiskCache(), isBlocking(), algorithmClass, cacheCapacity);
 302   
 
 303  45
         configureStandardListeners(newCache);
 304   
 
 305  45
         return newCache;
 306   
     }
 307   
 }
 308