// SimpleCache.java
//
//    A simple cache interface.
//
//    senger@ebi.ac.uk
//    November 2003
//

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

import java.io.IOException;
import java.util.Properties;


/**
 * An interface defining basic operation for caching data.
 * <p>
 *
 * @author <A HREF="mailto:senger@ebi.ac.uk">Martin Senger</A>
 * @version $Id: SimpleCache.java,v 1.4 2005/05/19 15:57:25 senger Exp $
 */
public interface SimpleCache {

    /**************************************************************************
     * Create a unique ID from the given parameters. The ID is used to
     * identify a cached object. Depending on the implementation it
     * can be a filename, a database primary key, or something
     * else. Its important characteristic, however, is that given the
     * same set of properties describing the cached object, the same
     * ID is always created.
     * <p>
     *
     * @param rootName is some high level name of the cached object
     * @param semanticType is yet another feature of the cached object
     * @param syntaxType is another property of the cached object
     * (e.i. it may be used as the file name suffix if the cache is
     * implemented as a filesystem)
     * @param lastModified is time in millis indicating when the
     * cached object was created or modified
     * @param props are all remaining properties identifying the
     * cached object
     *
     * @return a unique ID that can be used in other methods defined
     * in this interface in order to identify the same cached object
     **************************************************************************/
    String createId (String rootName,
		     String semanticType, String syntaxType,
		     long lastModified,
		     Properties props);

    /**************************************************************************
     * Is the object identified by its 'id' already cached?
     * <p>
     *
     * @param id a unique ID of the cached (or possibly cached) object
     * @return true if the object identified by 'id' already exists in
     * this cache
     **************************************************************************/
    boolean existsInCache (String id);

    /**************************************************************************
     * Return 'data' identified by 'id'.
     *
     * @param id a unique ID of the object being returned
     * @return data previously stored under 'id'; or null if such data
     * do not exist
     * @throws IOExcepiton if the retrieving failed
     **************************************************************************/
    java.lang.Object getContents (String id)
	throws IOException;

    /**************************************************************************
     * Store/cache 'data' 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, java.lang.Object data)
	throws IOException;

    /**************************************************************************
     * Remove cached object identified by its 'id' from the cache.
     * <p>
     *
     * @param id a unique ID
     * @throws IOException if the object exists but cannot be removed
     * (meaning that it <b>does not</b> raise any exception if the
     * object is not anymore in the cache)
     **************************************************************************/
    void removeFromCache (String id)
	throws IOException;

}