/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License (the "License").
 * You may not use this file except in compliance with the License.
 *
 * See LICENSE.txt included in this distribution for the specific
 * language governing permissions and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at LICENSE.txt.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information: Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 */

/*
 * Copyright (c) 2006, 2012, Oracle and/or its affiliates. All rights reserved.
 */
package org.opensolaris.opengrok.history;

import java.io.File;
import java.util.Date;
import java.util.Map;

interface HistoryCache {

    /**
     * Create and initialize an empty history cache if one doesn't exist
     * already.
     *
     * @throws HistoryException if initialization fails
     */
    void initialize() throws HistoryException;

    /**
     * Check whether this cache implementation can store history for the given
     * repository.
     *
     * @param repository the repository to check
     * @return {@code true} if this cache implementation can store history
     * for the repository, or {@code false} otherwise
     */
    boolean supportsRepository(Repository repository);

    /**
     * Retrieve the history for the given path, either from the cache or by
     * parsing the history information in the repository.
     *
     * @param path          The path to retrieve history for
     * @param parserClass   The class that implements the parser to use
     * @param repository    The external repository to read the history from 
     *      (can be <code>null</code>)
     * @param withFiles If {@code true} the returned history will contain
     *      a list of files touched by each changeset (the file list may be 
     *      skipped if {@code false}, but it doesn't have to)
     * @param isDir     If {@code null} the returned history type (file or
     *      directory) gets determined automatically: if path physically exists
     *      and is a directory, directory is assumed, file otherwise.
     *      If {@code true} this method blindly assumes type directory and a 
     *      directory history gets returned, otherwise a file history.
     * @return the history for the given path.
     * @throws HistoryException if no history could be obtained dueto an error.
     */
    History get(File path, Repository repository, boolean withFiles, Boolean isDir)
        throws HistoryException;

    /**
     * Store the history for a repository.
     *
     * @param history The history to store
     * @param repository The repository whose history to store
     * @throws HistoryException if the history cannot be stored
     */
    void store(History history, Repository repository)
            throws HistoryException;

    /**
     * Optimize how the history is stored on disk. This method is typically
     * called after the cache has been populated, or after large modifications
     * to the cache. The exact effect of this method is specific to each
     * implementation, but it may for example include compressing, compacting
     * or reordering the disk image of the cache in order to optimize
     * performance or space usage.
     *
     * @throws HistoryException if an error happens during optimization
     */
    void optimize() throws HistoryException;

    /**
     * Check if the specified directory is present in the cache.
     * @param directory the directory to check
     * @param repository the repository in which the directory is stored
     * @return {@code true} if the directory is in the cache, {@code false}
     * otherwise
     * @throws HistoryException if no history could be obtained dueto an error.
     */
    boolean hasCacheForDirectory(File directory, Repository repository)
            throws HistoryException;

    /**
     * Get the revision identifier for the latest cached revision in a
     * repository.
     *
     * @param repository the repository whose latest revision to return
     * @return a string representing the latest revision in the cache, or
     * {@code null} if it is unknown
     * @throws HistoryException if no history could be obtained dueto an error.
     */
    String getLatestCachedRevision(Repository repository)
            throws HistoryException;

    /**
     * Get the last modified times for all files and subdirectories in the
     * specified directory.
     *
     * @param directory which directory to fetch modification times for
     * @param repository the repository in which the directory lives
     * @param path2rev where to store the path to revision entries. If 
     *  {@code null}, revisions get simply ignored.
     * @return a map from file names to modification times
     * @throws HistoryException if no history could be obtained dueto an error.
     */
    Map<String, Date> getLastModifiedTimes(File directory, Repository repository,
        Map<String,String> path2rev) throws HistoryException;

    /**
     * Get the last modified times for all subdirectories in the
     * source root directory.
     *
     * @param path2rev where to store the path to revision entries. If 
     *  {@code null}, revisions get simply ignored.
     * @return a map from file names to modification times
     * @throws HistoryException if no history could be obtained dueto an error.
     */
    Map<String, Date> getLastModifiedTimes(Map<String, String> path2rev)
        throws HistoryException;

    /**
     * Clear the history cache for a repository.
     *
     * @param repository the repository whose cache to clear
     * @throws HistoryException if the cache couldn't be cleared
     */
    void clear(Repository repository) throws HistoryException;

    /**
     * Get a string with information about the history cache.
     *
     * @return a free form text string describing the history cache instance
     * @throws HistoryException if an error occurred while getting the info
     */
    String getInfo() throws HistoryException;

}