Class DiskCache

java.lang.Object
uk.ac.starlink.ttools.plot2.data.DiskCache

public class DiskCache extends 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 final String
     
    static final String
     
  • Constructor Summary

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

    Modifier and Type
    Method
    Description
    void
    Records that a file has been added to the cache.
    static String
    formatByteSize(long nbyte)
    Formats a string representing a number of bytes for human consumption.
    static long
    Returns a cacheLimit value that is suitable for general usage.
    Returns the directory associated with this cache.
    static File
    Returns the default system scratch directory.
    Returns a string summarising total cache files written to date.
    static String
    Returns a default-length hash string corresponding to a given string.
    static String
    hashText(String txt, int nchar)
    Returns a configurable-length hash string corresponding to a given string.
    void
    log(String txt)
    Logging utility function.
    static boolean
    mkdirs(File dir, boolean ownerOnly)
    Creates a scratch directory and any missing parents, assigning write privileges for all or owner-only.
    void
    Ensures that this cache's directory is ready for use.
    void
    Removes files from this cache's directory if it contains more data than the configured cache limit.
    static File
    toCacheDir(File baseDir, String label)
    Constructs a cache directory path given a base directory and a purpose-specific label.
    void
    touch(File file)
    Updates the lastModified timestamp for a given file.
    static 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
  • Field Details

  • Constructor Details

    • DiskCache

      public DiskCache(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 Details

    • getDir

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

      public void fileAdded(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 IOException
      Ensures that this cache's directory is ready for use. Should be called before the cache is used.
      Throws:
      IOException
    • log

      public void log(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 String getWriteSummary()
      Returns a string summarising total cache files written to date.
      Returns:
      summary text
    • touch

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

      public static String hashText(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 String hashText(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 File toWorkFilename(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 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 File getSystemTmpDir()
      Returns the default system scratch directory. This is supplied from the java.io.tmpdir system property.
      Returns:
      scratch directory
    • toCacheDir

      public static File toCacheDir(File baseDir, 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(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(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