/*
* 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;
}