tribble.io
Class DiskCacheManager

java.lang.Object
  extended by tribble.io.DiskCacheManager
All Implemented Interfaces:
FileCacheManagerI

public class DiskCacheManager
extends java.lang.Object
implements FileCacheManagerI

Disk file cache manager.

Manages a set of files in a local disk directory as a cache of document files.

Usage

To create a cache that stores files in a local disk directory, create a disk cache manager object, and establish the local directory and index file it should use:

    try
    {
        DiskCacheManager    cache;
        File                dir;

        dir = ...;
        cache = new DiskCacheManager();
        cache.open(dir, "mycache.ind");
    }
    catch (IOException ex)
    {
        ... error ...
    }
 

New document files can be added to the directory cache:

    try
    {
        File    fname;
        String  docId;

        docId = ...;
        fname = cache.createFile(id);
    }
    catch (IOException ex)
    {
        ... error ...
    }
 

The createFile(java.lang.String) method creates a new file within the cache directory and returns its name. The document-ID specified must be unique within the cache, i.e., no other document file within the cache can have the same document-ID. (A IOException is thrown if the document-ID is not unique.) The returned filename is guaranteed to be unique within the cache directory. From that point on, there is a one-to-one correspondence between the document-ID and the cached filename.

By default, the created filenames have a name that is prefixed with "temp" and suffixed with "tmp". However, these can be changed by client code:

    cache.setFilePrefix("mine");                // Or whatever
    cache.setFileSuffix("doc");                 // Or whatever
 

 

Data can be written to and read from the cached filename by client code. The file need not remain open (or be opened at all, for that matter) while the cache manager is active.

Once the cached filename is no longer needed, it can be removed from the cached directory:

    try
    {
        cache.removeFile(id);
    }
    catch (IOException ex)
    {
        ... error ...
    }
 

Once this is done, there is no longer any association between the document-ID and any filename in the cache directory.

Notes

A control file is maintained in the local cache directory, containing the names of all of the files that currently reside in the cache. This file is updated any time a document file is added to or removed from the cache.

The control file is read whenever the cache directory is opened by a document cache manager object, in order to re-establish the contents of the cache directory.

The default name of the control file is "cache.ind", but this can be specified when calling the open(java.io.File, java.lang.String) method.

To allow multiple cache directory managers to use the same disk directory, a lock file is used to insure mutually exclusive access to the directory.

Since:
2002-06-04
Version:
$Revision: 1.2 $ $Date: 2002/06/07 04:10:25 $
Author:
David R. Tribble, david@tribble.com
Copyright 2002 by David R. Tribble, all rights reserved.

Field Summary
static java.lang.String CONTROL_FILE_VERS
          Cache directory control file format version number.
static java.lang.String DFL_CONTROL_FILENAME
          Default cache directory control filename.
static int DFL_EXPIRY_DAYS
          Default number of days until cached files expire.
static java.lang.String DFL_PREFIX
          Default cache filename prefix.
static java.lang.String DFL_SUFFIX
          Default cache filename suffix.
(package private) static char ENTRY_SEP
          Cache control file entry field separator.
protected  java.io.File m_dir
          Local cache directory name.
protected  int m_expiryDays
          Days past the last access date that document files expire.
protected  java.util.HashMap m_files
          Files currently residing in the local directory cache.
protected  java.io.File m_indexFname
          Local cache directory index (control) file.
protected  java.io.File m_lockFname
          Local cache directory lock (mutex) file.
protected  java.lang.String m_pref
          Cache filename prefix.
protected  java.lang.String m_suff
          Cache filename suffix.
(package private) static java.lang.String REV
          Revision information.
 
Constructor Summary
DiskCacheManager()
          Default constructor.
 
Method Summary
 void close()
          Close this cache directory manager.
 java.io.File createFile(java.lang.String docId)
          Create a new cached filename in the cache directory for a given document-ID.
protected  void finalize()
          Finalization.
protected  DiskCacheFile findFile(java.lang.String docId)
          Locate the cached filename for a given document-ID within the cache index.
 java.io.File getFile(java.lang.String docId)
          Retrieve the cached filename for a given document-ID within the cache directory.
protected  void loadEntries()
          Read the index table for this cache directory manager from the cache directory.
protected  void lock()
          Acquire an exclusive lock on the index file of this cache directory.
 void open(java.io.File dir, java.lang.String index)
          Open the disk cache directory and initialize this cache manager.
protected static java.lang.String readEntryLine(java.io.BufferedReader in)
          Read a text line from the cache directory index (control) file.
 void removeAllExpiredFiles()
          Delete all expired document files from this cache directory.
 void removeAllFiles()
          Delete all document files from this cache directory.
protected  void removeExpiredEntries()
          Remove all the expired document files from the cache directory.
 void removeFile(java.lang.String docId)
          Delete a given document file from the cache directory.
 void setExpiryDays(int nDays)
          Establish the minimum lifetime of document files that reside in this cache directory.
 void setFilePrefix(java.lang.String pre)
          Set the filename prefix for document files in this cache directory.
 void setFileSuffix(java.lang.String suf)
          Set the filename suffix for document files in this cache directory.
protected  void storeEntries()
          Write the index table for this cache directory manager to the cache directory.
protected  void unlock()
          Release an exclusive lock on the index file of this cache directory.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

REV

static final java.lang.String REV
Revision information.

See Also:
Constant Field Values

DFL_CONTROL_FILENAME

public static final java.lang.String DFL_CONTROL_FILENAME
Default cache directory control filename.

See Also:
Constant Field Values

CONTROL_FILE_VERS

public static final java.lang.String CONTROL_FILE_VERS
Cache directory control file format version number.

See Also:
Constant Field Values

DFL_PREFIX

public static final java.lang.String DFL_PREFIX
Default cache filename prefix.

See Also:
Constant Field Values

DFL_SUFFIX

public static final java.lang.String DFL_SUFFIX
Default cache filename suffix.

See Also:
Constant Field Values

DFL_EXPIRY_DAYS

public static final int DFL_EXPIRY_DAYS
Default number of days until cached files expire.

See Also:
Constant Field Values

ENTRY_SEP

static final char ENTRY_SEP
Cache control file entry field separator.

See Also:
Constant Field Values

m_dir

protected java.io.File m_dir
Local cache directory name.


m_indexFname

protected java.io.File m_indexFname
Local cache directory index (control) file.


m_lockFname

protected java.io.File m_lockFname
Local cache directory lock (mutex) file.


m_pref

protected java.lang.String m_pref
Cache filename prefix.


m_suff

protected java.lang.String m_suff
Cache filename suffix.


m_expiryDays

protected int m_expiryDays
Days past the last access date that document files expire.


m_files

protected java.util.HashMap m_files
Files currently residing in the local directory cache.

This is a hash table keyed by document-IDs, which are unique to each document file contained in the local cache directory. The value of each hash entry is a DiskCacheFile object that contains the name of the file in the local cache, as well as other information, for the document file.

Constructor Detail

DiskCacheManager

public DiskCacheManager()
Default constructor.

Since:
1.1, 2002-06-04
Method Detail

open

public void open(java.io.File dir,
                 java.lang.String index)
          throws java.io.IOException
Open the disk cache directory and initialize this cache manager.

Specified by:
open in interface FileCacheManagerI
Parameters:
dir - A directory name to be used as the local file cache.
index - A filename residing within the local cache directory to be used as a index (control) file. This can be null or empty (""), in which case a default index filename is used.
Throws:
java.io.IOException - Thrown if access to the directory is denied or some other error occurs.
Since:
1.1, 2002-06-05
See Also:
close()

close

public void close()
           throws java.io.IOException
Close this cache directory manager.

Specified by:
close in interface FileCacheManagerI
Throws:
java.io.IOException - Thrown if access to the directory is denied or some other error occurs.
Since:
1.1, 2002-06-04
See Also:
open(java.io.File, java.lang.String)

setFilePrefix

public void setFilePrefix(java.lang.String pre)
                   throws java.io.IOException
Set the filename prefix for document files in this cache directory.

Parameters:
pre - A filename prefix. This should generally be a fairly short string, such as three characters.
Throws:
java.io.IOException - Thrown if pre is malformed.
Since:
1.1, 2002-06-04
See Also:
createFile(java.lang.String)

setFileSuffix

public void setFileSuffix(java.lang.String suf)
                   throws java.io.IOException
Set the filename suffix for document files in this cache directory.

Parameters:
suf - A filename suffix. This should generally be a fairly short string, such as three characters, plus a leading dot ('.').
Throws:
java.io.IOException - Thrown if suf is malformed.
Since:
1.1, 2002-06-04
See Also:
createFile(java.lang.String)

setExpiryDays

public void setExpiryDays(int nDays)
Establish the minimum lifetime of document files that reside in this cache directory.

Parameters:
nDays - The minimum number of days beyond their last access date that document files are allowed to reside in the cache directory before being automatically deleted.

If nDays is zero or negative, cached files will be deleted when method close() is called for this cache directory.

By default, cached files will exist for a minimum of DFL_EXPIRY_DAYS days.

Since:
1.1, 2002-06-04
See Also:
removeAllExpiredFiles()

createFile

public java.io.File createFile(java.lang.String docId)
                        throws java.io.IOException
Create a new cached filename in the cache directory for a given document-ID.

Specified by:
createFile in interface FileCacheManagerI
Parameters:
docId - A document-ID to create. This name must be unique within this cache. This name may contain any characters except newlines ('\n'), although it is recommended that it be composed of only printable characters.
Returns:
The filename of a newly created file in the cache directory corresponding to, and uniquely identified by, document-ID docId.
Throws:
java.io.IOException - Thrown if document-ID docId already exists in the cache, or if the cache directory could not be accessed, or if some other error occurs.
Since:
1.1, 2002-06-04
See Also:
getFile(java.lang.String), removeFile(java.lang.String)

getFile

public java.io.File getFile(java.lang.String docId)
                     throws java.io.IOException
Retrieve the cached filename for a given document-ID within the cache directory.

This method updates the last access time for the cached file.

Specified by:
getFile in interface FileCacheManagerI
Parameters:
docId - A document-ID to locate.
Returns:
The filename of the document file residing in the local cache directory that is uniquely identified by docId.
Throws:
java.io.IOException - Thrown if the document file does not exist, or if the cache directory could not be accessed, or if some other error occurs.
Since:
1.1, 2002-06-04
See Also:
createFile(java.lang.String), removeFile(java.lang.String)

removeFile

public void removeFile(java.lang.String docId)
                throws java.io.IOException
Delete a given document file from the cache directory.

Specified by:
removeFile in interface FileCacheManagerI
Parameters:
docId - The document-ID of a document file to delete from the cache directory.
Throws:
java.io.IOException - Thrown if the document file does not exist, or if the cache directory could not be accessed, or if some other error occurs.
Since:
1.1, 2002-06-04
See Also:
removeAllFiles(), removeAllExpiredFiles()

removeAllFiles

public void removeAllFiles()
                    throws java.io.IOException
Delete all document files from this cache directory.

Specified by:
removeAllFiles in interface FileCacheManagerI
Throws:
java.io.IOException - Thrown if the cache directory could not be accessed, or if some other error occurs.
Since:
1.1, 2002-06-04
See Also:
removeFile(java.lang.String), removeAllExpiredFiles()

removeAllExpiredFiles

public void removeAllExpiredFiles()
                           throws java.io.IOException
Delete all expired document files from this cache directory.

Throws:
java.io.IOException - Thrown if the cache directory could not be accessed, or if some other error occurs.
Since:
1.1, 2002-06-04
See Also:
setExpiryDays(int), removeAllFiles()

readEntryLine

protected static java.lang.String readEntryLine(java.io.BufferedReader in)
                                         throws java.io.IOException
Read a text line from the cache directory index (control) file.

Comment lines (which have a '#' in the leftmost column) are ignored.

Returns:
A single text line read from the index (control) file, or null if the end of the file has been reached.
Throws:
java.io.IOException - Thrown if a read error occurs, or if some other error occurs.
Since:
1.1, 2002-06-05
See Also:
storeEntries()

finalize

protected void finalize()
Finalization.

Overrides:
finalize in class java.lang.Object
Since:
1.1, 2002-06-04
See Also:
close()

findFile

protected DiskCacheFile findFile(java.lang.String docId)
                          throws java.io.IOException
Locate the cached filename for a given document-ID within the cache index. Note: Methods that call this method should be synchronized.

Parameters:
docId - A document-ID to locate.
Returns:
The document file entry residing in the local cache directory.
Throws:
java.io.IOException - Thrown if document-ID docId does not exist within this cache.
Since:
1.1, 2002-06-04
See Also:
getFile(java.lang.String)

loadEntries

protected void loadEntries()
                    throws java.io.IOException
Read the index table for this cache directory manager from the cache directory. Note: Methods that call this method should be synchronized.

Throws:
java.io.IOException - Thrown if a read error occurs, or if some other error occurs.
Since:
1.1, 2002-06-04
See Also:
storeEntries()

storeEntries

protected void storeEntries()
                     throws java.io.IOException
Write the index table for this cache directory manager to the cache directory. Note: Methods that call this method should be synchronized.

Throws:
java.io.IOException - Thrown if a write error occurs, or if some other error occurs.
Since:
1.1, 2002-06-04
See Also:
loadEntries()

removeExpiredEntries

protected void removeExpiredEntries()
                             throws java.io.IOException
Remove all the expired document files from the cache directory. Note: Methods that call this method should be synchronized.

Throws:
java.io.IOException - +INCOMPLETE
Since:
1.1, 2002-06-04
See Also:
removeAllExpiredFiles(), DiskCacheFile.hasExpired(java.util.Date)

lock

protected void lock()
             throws java.io.IOException
Acquire an exclusive lock on the index file of this cache directory. Note: Methods that call this method should be synchronized.

Throws:
java.io.IOException - Thrown if an I/O error occurs.
Since:
1.1, 2002-06-05

unlock

protected void unlock()
               throws java.io.IOException
Release an exclusive lock on the index file of this cache directory. Note: Methods that call this method should be synchronized.

Throws:
java.io.IOException - Thrown if an I/O error occurs.
Since:
1.1, 2002-06-05