1  /*
     2   * Licensed to the Apache Software Foundation (ASF) under one or more
     3   *  contributor license agreements.  The ASF licenses this file to You
     4   * under the Apache License, Version 2.0 (the "License"); you may not
     5   * use this file except in compliance with the License.
     6   * You may obtain a copy of the License at
     7   *
     8   *     http://www.apache.org/licenses/LICENSE-2.0
     9   *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.  For additional information regarding
    15   * copyright in this work, please see the NOTICE file in the top level
    16   * directory of this distribution.
    17   */
    18  
    19  package org.apache.roller.weblogger.util.cache;
    20  
    21  import org.apache.commons.logging.Log;
    22  import org.apache.commons.logging.LogFactory;
    23  
    24  
    25  /**
    26   * An LRU cache where entries expire after a given timeout period.
    27   */
    28  public class ExpiringLRUCacheImpl extends LRUCacheImpl {
    29      
             /* 
    P/P       *  Method: org.apache.roller.weblogger.util.cache.ExpiringLRUCacheImpl__static_init
              * 
              *  Postconditions:
              *    init'ed(log)
              */
    30      private static Log log = LogFactory.getLog(ExpiringLRUCacheImpl.class);
    31      
    32      private long timeout = 0;
    33      
    34      
    35      protected ExpiringLRUCacheImpl(String id) {
    36          
                 /* 
    P/P           *  Method: void org.apache.roller.weblogger.util.cache.ExpiringLRUCacheImpl(String)
                  * 
                  *  Postconditions:
                  *    init'ed(this.cache)
                  *    this.hits == +0
                  *    this.misses == +0
                  *    this.puts == +0
                  *    this.removes == +0
                  *    this.id == id
                  *    init'ed(this.id)
                  *    this.startTime == &new Date(LRUCacheImpl#1)
                  *    this.timeout == 3_600_000
                  *    new Date(LRUCacheImpl#1) num objects == 1
                  */
    37          super(id);
    38          this.timeout = 60 * 60 * 1000;
    39      }
    40      
    41      
    42      protected ExpiringLRUCacheImpl(String id, int maxsize, long timeout) {
    43          
                 /* 
    P/P           *  Method: void org.apache.roller.weblogger.util.cache.ExpiringLRUCacheImpl(String, int, long)
                  * 
                  *  Preconditions:
                  *    maxsize in -1_610_612_737..3_221_225_471
                  *    timeout <= 18_446_744_073_709_551
                  * 
                  *  Postconditions:
                  *    init'ed(this.cache)
                  *    this.hits == +0
                  *    this.misses == +0
                  *    this.puts == +0
                  *    this.removes == +0
                  *    this.id == id
                  *    init'ed(this.id)
                  *    this.startTime == &new Date(LRUCacheImpl#1)
                  *    this.timeout == One-of{0, timeout*1_000}
                  *    this.timeout in {0, 1_000..18_446_744_073_709_551_000}
                  *    ...
                  * 
                  *  Test Vectors:
                  *    timeout: {-263..0}, {1..18_446_744_073_709_551}
                  */
    44          super(id, maxsize);
    45          
    46          // timeout is specified in seconds; only positive values allowed
    47          if(timeout > 0) {
    48              this.timeout = timeout * 1000;
    49          }
    50      }
    51      
    52      
    53      /**
    54       * Store an entry in the cache.
    55       *
    56       * We wrap the cached object in our ExpiringCacheEntry object so that we
    57       * can track when the entry has expired.
    58       */
    59      public synchronized void put(String key, Object value) {
    60          
                 /* 
    P/P           *  Method: void put(String, Object)
                  * 
                  *  Preconditions:
                  *    init'ed(this.puts)
                  *    this.cache != null
                  *    init'ed(this.timeout)
                  * 
                  *  Postconditions:
                  *    this.puts == old this.puts + 1
                  *    init'ed(this.puts)
                  */
    61          ExpiringCacheEntry entry = new ExpiringCacheEntry(value, this.timeout);
    62          super.put(key, entry);
    63      }
    64      
    65      
    66      /**
    67       * Retrieve an entry from the cache.
    68       *
    69       * This LRU cache supports timeouts, so if the cached object has expired
    70       * then we return null, just as if the entry wasn't found.
    71       */
    72      public Object get(String key) {
    73          
                 /* 
    P/P           *  Method: Object get(String)
                  * 
                  *  Preconditions:
                  *    this.cache != null
                  *    (soft) log != null
                  *    (soft) init'ed(this.hits)
                  *    (soft) init'ed(this.misses)
                  *    (soft) init'ed(this.removes)
                  * 
                  *  Postconditions:
                  *    init'ed(return_value)
                  *    this.hits == One-of{old this.hits, old this.hits + 1, One-of{old this.hits, old this.hits + 1} - 1}
                  *    (soft) init'ed(this.hits)
                  *    this.misses == One-of{old this.misses + 1, old this.misses}
                  *    init'ed(this.misses)
                  *    this.removes == One-of{old this.removes, old this.removes + 1}
                  *    (soft) init'ed(this.removes)
                  * 
                  *  Test Vectors:
                  *    java.util.Map:get(...)@82: Addr_Set{null}, Inverse{null}
                  */
    74          Object value = null;
    75          ExpiringCacheEntry entry = null;
    76          
    77          synchronized(this) {
    78              entry = (ExpiringCacheEntry) super.get(key);
    79          }
    80          
    81          if (entry != null) {
    82              
    83              value = entry.getValue();
    84              
    85              // if the value is null then that means this entry expired
    86              if (value == null) {
    87                  log.debug("EXPIRED ["+key+"]");
    88                  hits--;
    89                  super.remove(key);
    90              }
    91          }
    92          
    93          return value;
    94      }
    95      
    96  }