// CentralCached.java
//
// Created: February 2008
//
// This file is a component of the BioMoby project.
// Copyright Martin Senger (martin.senger@gmail.com).
//

package org.biomoby.shared;

import org.biomoby.shared.MobyException;
import org.biomoby.shared.event.Notifier;
import java.util.Properties;

/**
 * A convenient interface combining together all methods for accessing
 * the BioMoby registry and the handling its local cache. <p>
 * 
 * @author <A HREF="mailto:martin.senger@gmail.com">Martin Senger</A>
 * @version $Id: CentralCached.java,v 1.2 2008/03/03 11:34:17 senger Exp $
 */
public interface CentralCached
    extends CentralAll, Notifier {

    /** A special file name, containing a list of cached entities. To
     * be ignored when browsing the cache. */
    static final String LIST_FILE = "__L__I__S__T__";

    /** A special file name, containing an RDF document with the
     * cached entities. To be ignored when browsing the cache. */
    static final String RDF_FILE = "__R__D__F__";

    /** An ID indicating data types part of a cache. */
    static final String CACHE_PART_DATATYPES = "c1";

    /** An ID indicating services part of a cache. */
    static final String CACHE_PART_SERVICES = "c2";

    /** An indicating service types part of a cache. */
    static final String CACHE_PART_SERVICETYPES = "c3";

    /** An ID indicating namespaces part of a cache. */
    static final String CACHE_PART_NAMESPACES = "c4";

    //
    // names of a cache properties
    //
    static final String CACHE_PROP_NAME = "cache-name";

    static final String CACHE_PROP_COUNT = "cache-count";

    static final String CACHE_PROP_OLDEST = "cache-oldest";

    static final String CACHE_PROP_YOUNGEST = "cache-youngest";

    static final String CACHE_PROP_SIZE = "cache-size";

    static final String CACHE_PROP_LOCATION = "cache-loc";

    static final String CACHE_PROP_REGISTRY_URL = "cache-reg-url";

    /***************************************************************************
     * Remove a group of objects from a cache. If 'id' is null it
     * removes the whole cache (for that Moby registry an instance
     * implementing this interface was initiated for). Otherwise 'id'
     * indicates which part of the cache that will be removed.  <p>
     * 
     * @param id
     *                should be either null, or one of the following:
     *                {@link #CACHE_PART_DATATYPES},
     *                {@link #CACHE_PART_SERVICES},
     *                {@link #CACHE_PART_SERVICETYPES}, and {@link
     *                #CACHE_PART_NAMESPACES}.
     **************************************************************************/
    void removeFromCache (String id);

    /***************************************************************************
     * Update the indicated part of a cache. If 'id' is null it
     * updates the whole cache (for that Moby registry an instance
     * implementing this interface was initiated for).  <p>
     * 
     * Updates means to fetch a new list of entities, compare it with
     * existing entities in the cache, fetch the missing ones and
     * remove the redundant ones.  <p>
     * 
     * @param id
     *                should be either null, or one of the following:
     *                {@link #CACHE_PART_DATATYPES},
     *                {@link #CACHE_PART_SERVICES},
     *                {@link #CACHE_PART_SERVICETYPES}, and {@link
     *                #CACHE_PART_NAMESPACES}.
     * 
     **************************************************************************/
    void updateCache (String id)
	throws MobyException;

    /***************************************************************************
     * Return an age of the current (whole) cache in millis from the
     * beginning of the Epoch; or -1 if cache is empty, or the age is
     * unknown. <p>
     * 
     * @return the cache age which is taken as the oldest (but filled) cache
     *         part (part is considered e.g. 'services', or 'data types', not
     *         their individual records in the parts)
     **************************************************************************/
    long getCacheAge();

    /***************************************************************************
     * Return as many properties describing the given part of a cache
     * as possible. The key used for returned properties are publicly
     * available from this interface but other may be returned as
     * well.  <p>
     * 
     * @return properties describing a cache
     * @param id
     *                is a part of cache to be described, or null if the whole
     *                cache should be described (this may return different kind
     *                of properties than for individual cache parts)
     **************************************************************************/
    Properties getCacheInfo (String id);

    /***************************************************************************
     * Similar as {@link #getCacheInfo} but formatted into a single
     * string. <p>
     * 
     * @return a cache description
     * @param id
     *                is a part of cache to be described, or null if the whole
     *                cache should be described (this may return different kind
     *                of properties than for individual cache parts)
     **************************************************************************/
    String getCacheInfoFormatted (String id);

    /***************************************************************************
     * Indicate whether the implementtaion really is using a local cache. <p>
     * 
     * @return true if a local cache is used
     **************************************************************************/
    boolean isUsingCache();

}