tribble.io
Interface FileCacheManagerI

All Known Implementing Classes:
DiskCacheManager

public interface FileCacheManagerI

Document file cache manager.

Classes that implement this interface manage a set of document files in a cache. The term document file is rather loosely defined, and denotes any kind of data object that can be specified by a File object and which is uniquely identified by a document-ID string. Similarly, the term cache is rather loosely defined, and denotes a collection of one or more document files.

Usage

Classes that implement this interface should provide a no-argument (default) constructor:

    class MyCacheManager
        implements FileCacheManagerI
    {
        // Constructor
        public MyCacheManager()
        {
            ...
        }

        ...
    }
 
To create a cache that stores files in a cache, create a cache manager object, and establish the local cache directory and index file it should use:
    try
    {
        FileCacheManagerI   cache;
        File                dir;

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

New document files can be added to the 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 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. From that point on, there is a one-to-one correspondence between the document-ID and the cached filename.

Data can be written to and read from the cached filename by client code.

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

    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.

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

Field Summary
static java.lang.String REV
          Revision information.
 
Method Summary
 void close()
          Close this cache manager.
 java.io.File createFile(java.lang.String docId)
          Create a new cached filename in this cache for a given document-ID.
 java.io.File getFile(java.lang.String docId)
          Retrieve the cached filename for a given document-ID within this cache.
 void open(java.io.File dir, java.lang.String index)
          Open the cache and initialize this cache manager.
 void removeAllFiles()
          Remove all document files from this cache.
 void removeFile(java.lang.String docId)
          Remove a given document file from this cache.
 

Field Detail

REV

static final java.lang.String REV
Revision information.

See Also:
Constant Field Values
Method Detail

open

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

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

close

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

Throws:
java.io.IOException - Thrown if access to the cache is denied or some other error occurs.
Since:
1.1, 2002-06-06
See Also:
open(java.io.File, java.lang.String)

createFile

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

Parameters:
docId - A document-ID to create. This name must be unique within this cache.
Returns:
The filename of a newly created file in the cache 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 could not be accessed, or if some other error occurs.
Since:
1.1, 2002-06-06
See Also:
getFile(java.lang.String), removeFile(java.lang.String)

getFile

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

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

removeFile

void removeFile(java.lang.String docId)
                throws java.io.IOException
Remove a given document file from this cache.

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

removeAllFiles

void removeAllFiles()
                    throws java.io.IOException
Remove all document files from this cache.

Throws:
java.io.IOException - Thrown if the cache could not be accessed, or if some other error occurs.
Since:
1.1, 2002-06-06
See Also:
removeFile(java.lang.String)