* 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 {@link java.io.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 {@link #createFile} 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 {@link java.io.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.
*
*
* @version $Revision: 1.1 $ $Date: 2002/06/07 04:14:37 $
* @since 2002-06-06
* @author
* David R. Tribble,
* david@tribble.com
*
* Copyright ©2002 by David R. Tribble, all rights reserved.
*/
public interface FileCacheManagerI
{
// Identification
/** Revision information. */
static final String REV =
"@(#)tribble/io/FileCacheManagerI.java $Revision: 1.1 $ $Date: 2002/06/07 04:14:37 $\n";
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Public methods
/***************************************************************************
* Open the cache and initialize this cache manager.
*
* @param dir
* A filename (which is typically the name of a local file directory) to be
* used as the local file cache.
*
* @param 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 IOException
* Thrown if access to the cache is denied or some other error occurs.
*
* @since 1.1, 2002-06-06
*
* @see #close
*/
public void open(File dir, String index)
throws IOException;
/***************************************************************************
* Close this cache manager.
*
* @throws IOException
* Thrown if access to the cache is denied or some other error occurs.
*
* @since 1.1, 2002-06-06
*
* @see #open
*/
public void close()
throws IOException;
/***************************************************************************
* Create a new cached filename in this cache for a given document-ID.
*
* @param docId
* A document-ID to create. This name must be unique within this cache.
*
* @return
* The filename of a newly created file in the cache corresponding to, and
* uniquely identified by, document-ID docId.
*
* @throws 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 #getFile
* @see #removeFile
*/
public File createFile(String docId)
throws IOException;
/***************************************************************************
* Retrieve the cached filename for a given document-ID within this cache.
*
* @param docId
* A document-ID to locate.
*
* @return
* The filename of the document file residing in the local cache that is
* uniquely identified by docId.
*
* @throws 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 #createFile
* @see #removeFile
*/
public File getFile(String docId)
throws IOException;
/***************************************************************************
* Remove a given document file from this cache.
*
* @param docId
* The document-ID of a document file to delete from this cache.
*
* @throws 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 #removeAllFiles
*/
public void removeFile(String docId)
throws IOException;
/***************************************************************************
* Remove all document files from this cache.
*
* @throws IOException
* Thrown if the cache could not be accessed, or if some other error occurs.
*
* @since 1.1, 2002-06-06
*
* @see #removeFile
*/
public void removeAllFiles()
throws IOException;
}
// End FileCacheManagerI.java