/* 
    P/P   *  Method: org.apache.roller.weblogger.util.cache.LazyExpiringCacheEntry__static_init
          */
     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 java.io.Serializable;
    22  
    23  
    24  /**
    25   * A cache entry that is meant to expire in a lazy fashion.
    26   *
    27   * The way to use this class is to wrap the object you want to cache in an
    28   * instance of this class and store that in your cache.  Then when you want
    29   * to retrieve this entry you must input a last-expired time which can be
    30   * compared against the time this entry was cached to determine if the cached
    31   * entry is "fresh".  If the object is not fresh then we don't return it.
    32   *
    33   * This essentially allows us to track when an object is cached and then before
    34   * we can retrieve that cached object we must compare it with it's last known
    35   * invalidation time to make sure it hasn't expired.  This is useful because
    36   * instead of actively purging lots of cached objects from the cache at 
    37   * invalidation time, we can now be lazy and just invalidate them when we
    38   * actually try to retrieve the cached object.
    39   *
    40   * This is useful for Roller because we will no longer have to iterate through
    41   * the list of cached objects and inspect the keys to figure out what items to
    42   * invalidate.  Instead we can just sit back and let the items be invalidated as
    43   * we try to use them.
    44   */
    45  public class LazyExpiringCacheEntry implements Serializable {
    46      
    47      private Object value = null;
    48      private long timeCached = -1;
    49      
    50      
             /* 
    P/P       *  Method: void org.apache.roller.weblogger.util.cache.LazyExpiringCacheEntry(Object)
              * 
              *  Postconditions:
              *    init'ed(this.timeCached)
              *    this.value == item
              *    init'ed(this.value)
              */
    51      public LazyExpiringCacheEntry(Object item) {
    52          this.value = item;
    53          this.timeCached = System.currentTimeMillis();
    54      }
    55      
    56      
    57      /**
    58       * Retrieve the value of this cache entry if it is still "fresh".
    59       *
    60       * If the value has expired then we return null.
    61       */
    62      public Object getValue(long lastInvalidated) {
                 /* 
    P/P           *  Method: Object getValue(long)
                  * 
                  *  Preconditions:
                  *    init'ed(this.timeCached)
                  *    (soft) init'ed(this.value)
                  * 
                  *  Postconditions:
                  *    return_value == One-of{null, this.value}
                  *    (soft) init'ed(return_value)
                  * 
                  *  Test Vectors:
                  *    this.timeCached - lastInvalidated: {0..27_670_116_110_564_327_423}, {-27_670_116_110_564_327_423..-1}
                  */
    63          if(this.isInvalid(lastInvalidated)) {
    64              return null;
    65          } else {
    66              return this.value;
    67          }
    68      }
    69      
    70      
    71      /**
    72       * Determine if this cache entry has expired.
    73       */
    74      public boolean isInvalid(long lastInvalidated) {
    75          
                 /* 
    P/P           *  Method: bool isInvalid(long)
                  * 
                  *  Preconditions:
                  *    init'ed(this.timeCached)
                  * 
                  *  Postconditions:
                  *    init'ed(return_value)
                  */
    76          return (this.timeCached < lastInvalidated);
    77      }
    78  
    79      
    80      public long getTimeCached() {
                 /* 
    P/P           *  Method: long getTimeCached()
                  * 
                  *  Preconditions:
                  *    init'ed(this.timeCached)
                  * 
                  *  Postconditions:
                  *    return_value == this.timeCached
                  *    init'ed(return_value)
                  */
    81          return timeCached;
    82      }
    83      
    84  }