Class DiskCache


  • public class DiskCache
    extends java.lang.Object
    Represents a persistent cache based on named files in a given directory of a filesystem. This class does not provide all the required facilities for cache management, but it provides some methods which will be useful during such management.
    Since:
    16 Jan 2020
    Author:
    Mark Taylor
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String CACHE_DIRNAME  
      static java.lang.String README_NAME  
    • Constructor Summary

      Constructors 
      Constructor Description
      DiskCache​(java.io.File dir, long limit)
      Constructor.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void fileAdded​(java.io.File f)
      Records that a file has been added to the cache.
      static java.lang.String formatByteSize​(long nbyte)
      Formats a string representing a number of bytes for human consumption.
      static long getDefaultCacheLimit​(java.io.File dir)
      Returns a cacheLimit value that is suitable for general usage.
      java.io.File getDir()
      Returns the directory associated with this cache.
      static java.io.File getSystemTmpDir()
      Returns the default system scratch directory.
      java.lang.String getWriteSummary()
      Returns a string summarising total cache files written to date.
      static java.lang.String hashText​(java.lang.String txt)
      Returns a default-length hash string corresponding to a given string.
      static java.lang.String hashText​(java.lang.String txt, int nchar)
      Returns a configurable-length hash string corresponding to a given string.
      void log​(java.lang.String txt)
      Logging utility function.
      static boolean mkdirs​(java.io.File dir, boolean ownerOnly)
      Creates a scratch directory and any missing parents, assigning write privileges for all or owner-only.
      void ready()
      Ensures that this cache's directory is ready for use.
      void tidy()
      Removes files from this cache's directory if it contains more data than the configured cache limit.
      static java.io.File toCacheDir​(java.io.File baseDir, java.lang.String label)
      Constructs a cache directory path given a base directory and a purpose-specific label.
      void touch​(java.io.File file)
      Updates the lastModified timestamp for a given file.
      static java.io.File toWorkFilename​(java.io.File file)
      Produces a working filename to be used as temporary workspace when assembling a given destination filename.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • DiskCache

        public DiskCache​(java.io.File dir,
                         long limit)
        Constructor.
        Parameters:
        dir - directory into which cache files will be written
        limit - cache size indicator; if positive, it's the maximum cache size in bytes; if negative, it's the amount of space on the disk that cache usage tries to keep free; if zero, it's something adaptive
    • Method Detail

      • getDir

        public java.io.File getDir()
        Returns the directory associated with this cache.
        Returns:
        cache directory
      • fileAdded

        public void fileAdded​(java.io.File f)
        Records that a file has been added to the cache. This record is used to report persistently added files at shutdown. No check is made that the file in question actually was added.
        Parameters:
        f - file added
      • ready

        public void ready()
                   throws java.io.IOException
        Ensures that this cache's directory is ready for use. Should be called before the cache is used.
        Throws:
        java.io.IOException
      • log

        public void log​(java.lang.String txt)
        Logging utility function. This just passes a message to the logging system, using the logging level associated with this instance.
        Parameters:
        txt - message to log
      • tidy

        public void tidy()
        Removes files from this cache's directory if it contains more data than the configured cache limit.
      • getWriteSummary

        public java.lang.String getWriteSummary()
        Returns a string summarising total cache files written to date.
        Returns:
        summary text
      • touch

        public void touch​(java.io.File file)
        Updates the lastModified timestamp for a given file.
        Parameters:
        file - file to touch
      • hashText

        public static java.lang.String hashText​(java.lang.String txt)
        Returns a default-length hash string corresponding to a given string. This doesn't have to be cryptographically secure, but accidental collisions are to be avoided.
        Parameters:
        txt - text to hash
        Returns:
        fixed-length hash string
      • hashText

        public static java.lang.String hashText​(java.lang.String txt,
                                                int nchar)
        Returns a configurable-length hash string corresponding to a given string. This doesn't have to be cryptographically secure, but accidental collisions are to be avoided.
        Parameters:
        txt - text to hash
        nchar - number of characters in output (currently up to 32)
        Returns:
        hash string
      • toWorkFilename

        public static java.io.File toWorkFilename​(java.io.File file)
        Produces a working filename to be used as temporary workspace when assembling a given destination filename.

        We could just use one of the File.createTempFile methods, but attempt to come up with a name that is (a) likely to be unique and (b) bears some resemlance to the requested destination file, for ease of debugging etc.

        Parameters:
        file - destination file
        Returns:
        workspace file
      • formatByteSize

        public static java.lang.String formatByteSize​(long nbyte)
        Formats a string representing a number of bytes for human consumption.
        Parameters:
        nbyte - byte count
        Returns:
        storage size string
      • getSystemTmpDir

        public static java.io.File getSystemTmpDir()
        Returns the default system scratch directory. This is supplied from the java.io.tmpdir system property.
        Returns:
        scratch directory
      • toCacheDir

        public static java.io.File toCacheDir​(java.io.File baseDir,
                                              java.lang.String label)
        Constructs a cache directory path given a base directory and a purpose-specific label.
        Parameters:
        baseDir - base directory; if null, java.io.tmpdir is used
        label - purpose-specific label (used for subdirectory name)
        Returns:
        directory to which cache files can be written
      • mkdirs

        public static boolean mkdirs​(java.io.File dir,
                                     boolean ownerOnly)
        Creates a scratch directory and any missing parents, assigning write privileges for all or owner-only. This is like File.mkdirs(), but it allows the option of assigning global write privileges to any created directories.
        Parameters:
        dir - target directory
        ownerOnly - true to make created directories writable by ownwer only, false to make them writable by all
        Returns:
        true if creation succeeded
      • getDefaultCacheLimit

        public static long getDefaultCacheLimit​(java.io.File dir)
        Returns a cacheLimit value that is suitable for general usage. The return value is negative, meaning that it corresponds to requiring a certain number of bytes free on the filesystem.
        Parameters:
        dir - cache directory