tribble.io
Class DiskCacheManager

java.lang.Object
  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