Changeset 4827

Timestamp:

Mar 23, 2009, 1:09:35 PM (15 years ago)

Author:

Nicklas Nordborg

Message:

References #1261: Global cache for static data

The cache is now thread-safe. Configuration options in base.config are supported. Old files are cleaned up. Unless something shows up this should now be fully functional.

Location:

trunk

Files:

• config/dist/base.config (modified) (1 diff)
• doc/src/docbook/appendix/base.config.xml (modified) (1 diff)
• src/core/net/sf/basedb/core/Application.java (modified) (2 diffs)
• src/core/net/sf/basedb/util/OlderThanFileFilter.java (added)
• src/core/net/sf/basedb/util/StaticCache.java (modified) (7 diffs)

trunk/config/dist/base.config

@@ -155 +155 @@
 cache.timeout = 20
 
+# If the static cache should be disabled or enabled
+# Disabling the static cache may reduce performance for
+# certain operations
+cache.static.disabled = false
+
+# Timeout (in days) for items in the static cache
+# Items that hasn't been accessed in the configured amount of
+# of time will be removed from the cache
+cache.static.max-age = 30
+
 #Overwrite the existing help texts when updating the program
 helptext.update = true

trunk/doc/src/docbook/appendix/base.config.xml

@@ -592 +592 @@
       </listitem>
     </varlistentry>
+    
+    <varlistentry>
+      <term><property>cache.static.disabled</property></term>
+      <listitem>
+        <para>
+        If the static cache should be enabled or disabled. It is enabled by
+        default. Disabling the static cache may reduce performance in some
+        cases. The static cache is used to cache processed information,
+        for example images, so that the database doesn't have to be queried
+        on every request.
+          </para>
+      </listitem>
+    </varlistentry>
+    
+    <varlistentry>
+      <term><property>cache.static.max-age</property></term>
+      <listitem>
+        <para>
+        The maximum age in days of files in the static cache. Files that 
+        hasn't been accessed (read or written) in the specified amount
+        of time are deleted. 
+          </para>
+      </listitem>
+    </varlistentry>
+    
     <varlistentry>
       <term><property>helptext.update</property></term>

trunk/src/core/net/sf/basedb/core/Application.java

@@ -449 +449 @@
       // Initialise other utility classes
       staticCache = new StaticCache(new java.io.File(userFilesDirectory, "static.cache"));
+      staticCache.setDisabled(true);
       QueryExecutor.init();
       HibernateUtil.init1();
@@ -501 +502 @@
         RawDataTypes.initPlatforms();
   
-        // Adding a task that cleans the session control cache at regular intervale
+        // Adding a task that cleans the session control cache at regular intervals
         long milliSeconds = 60 * 1000 * sessionCacheTimeout;
         getScheduler().schedule(new SessionControlCacheCleaner(), milliSeconds, milliSeconds, false);
+        
+        // Adding a task that cleans the static cache at regular intervals
+        staticCache.setDisabled(Config.getBoolean("cache.static.disabled"));
+        if (!staticCache.isDisabled())
+        {
+          long maxFileAge = 24L * 3600L * 1000L * Config.getLong("cache.static.max-age", 30);
+          long checkInterval = 12 * 3600 * 1000; // Once every twelve hours
+          getScheduler().schedule(
+            staticCache.cleanUpTask(staticCache.olderThan(maxFileAge)), 60000, checkInterval, false);
+        }
         
         if (useInternalJobQueue == null) useInternalJobQueue = Config.getBoolean("jobqueue.internal.enabled");

trunk/src/core/net/sf/basedb/util/StaticCache.java

@@ -23 +23 @@
 
 import java.io.File;
+import java.io.FileFilter;
 import java.io.FileInputStream;
 import java.io.FileOutputStream;
+import java.io.FilterInputStream;
+import java.io.FilterOutputStream;
 import java.io.IOException;
 import java.io.InputStream;
@@ -31 +34 @@
 import java.io.OutputStream;
 import java.io.Serializable;
+import java.lang.ref.WeakReference;
+import java.util.List;
+import java.util.Map;
+import java.util.TimerTask;
+import java.util.WeakHashMap;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.locks.Lock;
+import java.util.concurrent.locks.ReadWriteLock;
+import java.util.concurrent.locks.ReentrantReadWriteLock;
+import java.util.regex.Pattern;
+
+import net.sf.basedb.core.InvalidDataException;
 
 /**
@@ -36 +51 @@
   use case is to store data this is expensive to get from the database
   in a file for later retrieval. The cache can be used in streaming mode
-  with the any of the {@link #read(String)} or {@link #write(String, InputStream)}
+  with the any of the {@link #read(String, int)} or {@link #write(String, InputStream, int)}
   methods and their variants. It can also be used to store any {@link Serializable}
-  object with {@link #store(String, Serializable)} and {@link #load(String)}.
+  object with {@link #store(String, Serializable, int)} and {@link #load(String, int)}.
   <p>
+  
   In all cases the cached entry is identified by a key which is more or
   less directly translated to directories on the file system.
   <p>
   
+  This class is thread-safe and can be used by multiple threads at the same
+  time. Write requests to the same entry in the cache are allowed to one 
+  thread at a time. Any number of threads may read from the same cache entry
+  as long as no thread is writing to that entry.
   
   @author Nicklas
@@ -51 +71 @@
 public class StaticCache
 {
+
+  public static final Pattern validKey = Pattern.compile("[\\w\\/\\.\\-]+");
+
+  /**
+    Log static cache events.
+  */
+  private static final org.apache.log4j.Logger log = 
+    org.apache.log4j.LogManager.getLogger("net.sf.basedb.util.StaticCache");
+
+  /**
+    Checks if the given key is a vilid cache entry key.
+    Allowed characters are: any alphanumerical character + ./-
+    @param key The key to check
+    @return TRUE if the key is valid
+  */
+  public static boolean isValidKey(String key)
+  {
+    return validKey.matcher(key).matches();
+  }
+  
   private final File root;
+  private final Map<String, LockEntry> locks;
   private boolean disabled;
+  
   
   /**
@@ -61 +103 @@
   {
     this.root = root;
+    this.locks = new WeakHashMap<String, LockEntry>();
+    log.info("Creating static cache in directory " + root);
   }
 
@@ -79 +123 @@
   public void setDisabled(boolean disabled)
   {
+    if (disabled)
+    {
+      log.info("Disabling static cache in directory " + root);
+    }
+    else
+    {
+      log.info("Enabling static cache in directory " + root);
+    }
     this.disabled = disabled;
   }
   
   /**
-    Store information in the cache. If the entry already exists,
+    Remove all files that matches the specified filter from
+    the cache. This method is synchronized and can only
+    be executed by one thread at a time.
+    
+    @param filter A file filter that matches the files to
+      remove
+  */
+  public synchronized void cleanUp(FileFilter filter)
+  {
+    log.info("Cleaning up static cache: " + root);
+    List<File> oldFiles = FileUtil.findFiles(root, filter);
+    if (oldFiles == null) return;
+    
+    log.debug("Found " + oldFiles.size() + " files that should be deleted");
+    int numDeleted = 0;
+    for (File f : oldFiles)
+    {
+      if (f.delete())
+      {
+        log.debug("Removed cached file: " + f);
+        numDeleted++;
+      }
+      else
+      {
+        log.warn("Failed to remove cached file: " + f);
+      }
+    }
+    log.info("Removed " + numDeleted + " files from the static cache: " + root);
+  }
+  
+  /**
+    Creates a file filter that matches all files that
+    are older than the specified age.
+    @param age The age in milliseconds
+    @return A file filter
+    @see OlderThanFileFilter
+  */
+  public FileFilter olderThan(long age)
+  {
+    return new OlderThanFileFilter(age, true);
+  }
+  
+  /**
+    Creates a task that cleans up this cache when it is 
+    executed.
+    @param filter The file filter that determines
+      which file that should be deleted
+    @return A TimerTask object
+    @see #cleanUp(FileFilter)
+  */
+  public TimerTask cleanUpTask(FileFilter filter)
+  {
+    return new CleanupTask(this, filter);
+  }
+  
+  /**
+    Store binary information in the cache. If the entry already exists,
     it is overwritten. If the entry is locked by other threads,
-    this thread wai
+    this thread waits the specified number of milliseconds before
+    returning.
     
     @param key The cache key
     @param in An input stream to read from
+    @param timeout A timeout in milliseconds to wait for a write lock
+      on the requested cache entry
     @return The number of bytes written
   */
-  public long write(String key, InputStream in)
+  public long write(String key, InputStream in, int timeout)
     throws IOException
   {
     if (disabled) return 0;
-    OutputStream out = getOutputStream(key);
-    long numBytes = FileUtil.copy(in, out);
-    out.flush();
-    out.close();
+    long numBytes = 0;
+    OutputStream out = null;
+    try
+    {
+      out = getOutputStream(key, timeout);
+      if (out != null)
+      {
+        numBytes = FileUtil.copy(in, out);
+        out.flush();
+      }
+    }
+    finally
+    {
+      if (out != null) out.close();
+    }
     return numBytes;
   }
   
-  public OutputStream write(String key)
+  /**
+    Get an output stream that can be used to write binary information
+    to the cache. If the entry already exists, it is overwritten. 
+    If the entry is locked by other threads, this thread waits the 
+    specified number of milliseconds before giving up.
+    <p>
+    NOTE! It is very important that the caller closes the 
+    output stream as soon as all data has been written to it.
+    Failure to do so may result in locking the cache entry from
+    reading by other threads.
+    
+    @param key The cache key
+    @param timeout A timeout in milliseconds to wait for a write lock
+      on the requested cache entry
+    @return An output stream, or null if a write lock could not
+      be aquired
+  */
+  public OutputStream write(String key, int timeout)
     throws IOException
   {
     if (disabled) return null;
-    return getOutputStream(key);
-  }
-  
-  
-  public long read(String key, OutputStream out)
+    return getOutputStream(key, timeout);
+  }
+  
+  /**
+    Read binary information from the cache. The contents of the 
+    specified cache entry will be copied to the specified output 
+    stream.
+
+    @param key The cache key
+    @param out An output stream to write the cache contents to
+    @param timeout A timeout in milliseconds to wait for a 
+      read lock on the requested cache entry
+    @return The number of bytes copied
+    @throws IOException
+  */
+  public long read(String key, OutputStream out, int timeout)
     throws IOException
   {
     if (disabled) return 0;
-    InputStream in = getInputStream(key);
     long numBytes = 0;
-    if (in != null) FileUtil.copy(in, out);
+    InputStream in = null;
+    try
+    {
+      in = getInputStream(key, timeout);
+      if (in != null) 
+      {
+        numBytes = FileUtil.copy(in, out);
+      }
+    }
+    finally
+    {
+      if (in != null) in.close();
+    }
     return numBytes;
   }
   
-  public InputStream read(String key)
+  /**
+    Get an input stream for reading binary information from the cache.
+  
+    @param key The cache key
+    @param timeout A timeout in milliseconds to wait for a 
+      read lock on the requested cache entry
+    @return An input stream or null if the cache entry doesn't exists
+      or if a read lock could not be aquired
+    @throws IOException
+  */
+  public InputStream read(String key, int timeout)
     throws IOException
   {
     if (disabled) return null;
-    return getInputStream(key);
-  }
-  
-  public boolean store(String key, Serializable object)
+    return getInputStream(key, timeout);
+  }
+  
+  /**
+    Store a serializable object in the cache. If the entry already exists,
+    it is overwritten. If the entry is locked by other threads,
+    this thread waits the specified number of milliseconds before
+    returning.
+    
+    @param key The cache key
+    @param object The object to store in the cache
+    @param timeout A timeout in milliseconds to wait for a write lock
+      on the requested cache entry
+    @return TRUE if the object could be stored, FALSE otherwise
+  */
+  public boolean store(String key, Serializable object, int timeout)
     throws IOException
   {
     if (disabled) return false;
-    ObjectOutputStream out = new ObjectOutputStream(getOutputStream(key));
-    out.writeObject(object);
-    out.flush();
-    out.close();
+    OutputStream out = null;
+    try
+    {
+      out = getOutputStream(key, timeout);
+      if (out != null)
+      {
+        ObjectOutputStream oos = new ObjectOutputStream(out);
+        oos.writeObject(object);
+        oos.flush();
+      }
+    }
+    finally
+    {
+      if (out != null) out.close();
+    }
     return true;
   }
   
-  public Serializable load(String key)
+  /**
+    Read a serializable object from the cache.
+    
+    @param key The cache key
+    @param timeout A timeout in milliseconds to wait for a read lock
+      on the requested cache entry
+    @return The materialized object, or null if the cache entry doesn't
+      exists or if a read lock couldn't be aquired
+  */
+  public Serializable load(String key, int timeout)
     throws IOException
   {
     if (disabled) return null;
-    InputStream in = getInputStream(key);
     Serializable object = null;
-    if (in != null)
-    {
-      ObjectInputStream oin = new ObjectInputStream(in);
-      try
-      {
-        object = (Serializable)oin.readObject();
-      }
-      catch (ClassNotFoundException ex)
-      {
-        throw new IOException(ex);
-      }
+    InputStream in = null;
+    try
+    {
+      in = getInputStream(key, timeout);
+      if (in != null)
+      {
+        ObjectInputStream oin = new ObjectInputStream(in);
+        try
+        {
+          object = (Serializable)oin.readObject();
+        }
+        catch (ClassNotFoundException ex)
+        {
+          throw new IOException(ex);
+        }
+      }
+    }
+    finally
+    {
+      if (in != null) in.close();
     }
     return object;    
@@ -161 +372 @@
   private void validateKey(String key)
   {
-    
-  }
-  
-  private InputStream getInputStream(String key)
+    if (!isValidKey(key))
+    {
+      throw new InvalidDataException("Invalid cache key: " + key);
+    }
+  }
+  
+  /**
+    Get a lock-safe input stream.
+  */
+  private InputStream getInputStream(String key, int timeout)
     throws IOException
   {
     validateKey(key);
+    log.debug("Read request for static cache: " + key);
     File f = new File(root, key);
-    if (!f.exists()) return null;
-    return new FileInputStream(f);
-  }
-
-  private OutputStream getOutputStream(String key)
+    if (!f.exists()) 
+    {
+      log.debug("Cache entry doesn't exist: " + key);
+      return null;
+    }
+    LockEntry lock = aquireLock(key, false, timeout);
+    if (lock == null) return null;
+    InputStream in = null;
+    try
+    {
+      f.setLastModified(System.currentTimeMillis());
+      in = new LockSafeInputStream(new FileInputStream(f), lock);
+    }
+    finally
+    {
+      if (in == null) lock.readLock().unlock();
+    }
+    return in;
+  }
+
+  /**
+    Get a lock-safe output stream.
+  */
+  private OutputStream getOutputStream(String key, int timeout)
     throws IOException
   {
     validateKey(key);
-    File f = new File(root, key);
-    f.getParentFile().mkdirs();
-    f.createNewFile();
-    return new FileOutputStream(f);
-  }
-
-  
+    log.debug("Write request for static cache: " + key);
+    LockEntry lock = aquireLock(key, true, timeout);
+    if (lock == null) return null;
+    OutputStream out = null;
+    try
+    {
+      File f = new File(root, key);
+      f.getParentFile().mkdirs();
+      f.createNewFile();
+      out = new LockSafeOutputStream(new FileOutputStream(f), lock);
+    }
+    finally
+    {
+      if (out == null) lock.writeLock().unlock();
+    }
+    return out;
+  }
+
+  /**
+    Aquire a read or write lock on a given cache entry.
+    @return A lock manager or null if the lock could not be aquired
+  */
+  private LockEntry aquireLock(String key, boolean writeLock, int timeout)
+  {
+    String lockType = writeLock ? "write" : "read";
+    log.debug("Trying to get " + lockType + " lock on: " + key);
+    LockEntry rwLock = null;
+    synchronized (locks)
+    {
+      log.debug("Number of known lock entries: " + locks.size());
+      rwLock = locks.get(key);
+      if (rwLock == null)
+      {
+        log.debug("Create new lock holder for: " + key);
+        rwLock = new LockEntry(new ReentrantReadWriteLock(), key);
+        locks.put(key, rwLock);
+      }
+    }
+    
+    Lock lock = writeLock ? rwLock.writeLock() : rwLock.readLock();
+    try
+    {
+      if (!lock.tryLock(timeout, TimeUnit.MILLISECONDS)) 
+      {
+        log.debug("Timeout while waiting for " + lockType + " lock on: " + key);
+        rwLock = null;
+      }
+    }
+    catch (InterruptedException ex)
+    {
+      log.debug("Interrupted while waiting for " + lockType + " lock on: " + key);
+      rwLock = null;
+    }
+    if (rwLock != null) log.debug("Got " + lockType + " lock on: " + key);
+    return rwLock;
+  }
+  
+  /**
+    A lock-safe output stream that releases the associated 
+    write lock when the stream is closed.
+    <p>
+    NOTE! It is important that we keep a strong reference
+    to the 'key' in this class until the stream is closed, 
+    since otherwise the locked entry may be reclaimed by the 
+    garbage collector.
+  */
+  static class LockSafeOutputStream
+    extends FilterOutputStream
+  {
+    private final Throwable calledFrom;
+    private ReadWriteLock lock;
+    private String key;
+    private boolean closed;
+
+    LockSafeOutputStream(OutputStream out, LockEntry lock)
+    {
+      super(out);
+      this.lock = lock;
+      this.key = lock.getKey();
+      this.calledFrom = new Throwable();
+    }
+
+    @Override
+    public void close() 
+      throws IOException
+    {
+      if (closed) return;
+      log.debug("Releasing write lock on: " + key);
+      lock.writeLock().unlock();
+      closed = true;
+      lock = null;
+      key = null;
+      super.close();
+    }
+    
+    @Override
+    protected void finalize()
+      throws Throwable
+    {
+      if (!closed) 
+      {
+        log.warn("Found unreleased write lock on: " + key, calledFrom);
+        close();
+      }
+      super.finalize();
+    }
+  
+    @Override
+    public String toString()
+    {
+      return "LockSafeOutputStream[" + key + "]";
+    }
+
+  }
+  
+  
+  /**
+    A lock-safe input stream that releases the associated 
+    read lock when the stream is closed.
+    <p>
+    NOTE! It is important that we keep a strong reference
+    to the 'key' in this class until the stream is closed, 
+    since otherwise the locked entry may be reclaimed by the 
+    garbage collector.
+  */
+  static class LockSafeInputStream
+    extends FilterInputStream
+  {
+  
+    private final Throwable calledFrom;
+    private ReadWriteLock lock;
+    private String key;
+    private boolean closed;
+  
+    LockSafeInputStream(InputStream in, LockEntry lock)
+    {
+      super(in);
+      this.lock = lock;
+      this.key = lock.getKey();
+      this.calledFrom = new Throwable();
+    }
+  
+    @Override
+    public void close() 
+      throws IOException
+    {
+      if (closed) return;
+      log.debug("Releasing read lock on: " + key);
+      lock.readLock().unlock();
+      closed = true;
+      lock = null;
+      key = null;
+      super.close();
+    }
+    
+    @Override
+    protected void finalize()
+      throws Throwable
+    {
+      if (!closed) 
+      {
+        log.warn("Found unreleased read lock on: " + key, calledFrom);
+        close();
+      }
+      super.finalize();
+    }
+    
+    @Override
+    public String toString()
+    {
+      return "LockSafeInputStream[" + key + "]";
+    }
+  }
+
+  /**
+    Keeps track of a locked cached entry. The 'key' is the same key
+    instance that was used to create the entry in the first place.
+    It is important that all active maintainers of a lock also
+    keeps a strong reference to the key since the lock entry may
+    otherwise be reclaimed by the garbage collector.
+  */
+  static class LockEntry
+    implements ReadWriteLock
+  {
+    private ReadWriteLock rwLock;
+    private WeakReference<String> keyRef;
+    
+    LockEntry(ReadWriteLock rwLock, String key)
+    {
+      this.rwLock = rwLock;
+      this.keyRef = new WeakReference<String>(key);
+    }
+    
+    @Override
+    public Lock writeLock()
+    {
+      return rwLock.writeLock();
+    }
+    
+    @Override
+    public Lock readLock()
+    {
+      return rwLock.readLock();
+    }
+    
+    public String getKey()
+    {
+      return keyRef.get();
+    }
+    
+    @Override
+    public String toString()
+    {
+      return "LockEntry[" + getKey() + "]";
+    }
+  }
+  
+  /**
+    A timer task that clean up the cache when it is executed.
+  */
+  public class CleanupTask
+    extends TimerTask
+  {
+
+    private final StaticCache cache;
+    private final FileFilter filter;
+    
+    public CleanupTask(StaticCache cache, FileFilter filter)
+    {
+      this.cache = cache;
+      this.filter = filter;
+    }
+    
+    @Override
+    public void run()
+    {
+      cache.cleanUp(filter);
+    }
+  }
 }