// SimpleFileCache.java
//
//    senger@ebi.ac.uk
//    October 2004
//

// TBD: this may go later to the general tools
package org.biomoby.client;

import java.io.IOException;


/**
 * An interface extending basic operations for caching data by
 * pointing users directly to files with cached objects or for cached
 * objects. This allows to use such files directly by other classes or
 * even by external processes. Of course, the implementation should
 * make sure that nobody is stepping on others toes. <p>
 *
 * @author <A HREF="mailto:senger@ebi.ac.uk">Martin Senger</A>
 * @version $Id: SimpleFileCache.java,v 1.3 2005/05/19 15:57:25 senger Exp $
 */
public interface SimpleFileCache
    extends SimpleCache {

    /**************************************************************************
     * Return a fully qualified path to a file that represents the
     * cached object identified by the 'id'. Note that this file does
     * not need to exist yet (if no object with given 'id' was stored)
     * - but the path to the file must exist, and if not it must be
     * created by this method. <p>
     *
     * @param id a unique ID of the cached (or possibly cached) object
     * @return a filename with the full path representing an object 'id'
     * @throws IOException if creating the parent directories caused problem
     **************************************************************************/
    String getFilename (String id)
	throws IOException;

    /**************************************************************************
     * Store 'data' as an object identified by 'id'.
     *
     * @param id a unique ID of the object being stored
     * @param data are being stored
     * @throws IOExcepiton if the storing failed
     **************************************************************************/
    void setContents (String id, byte[] data)
	throws IOException;

    /**************************************************************************
     * Return a full URL allowing to retrieve a cached object
     * identified by its 'id'.
     * <p>
     *
     * @param id a unique ID 
     **************************************************************************/
    String getURL (String id);

    /**************************************************************************
     * Remove all cached objects that are in cache longer that
     * specifies by 'millis'.  <p>
     *
     * @param millis how many milliseconds must be an object stored to
     * be remopved by calling this method
     * @throws IOException if any object that exists in the cache and
     * is targeted to be removed but cannot be removed
     **************************************************************************/
    void removeOlderThen (long millis)
	throws IOException;

}