1 /* 2 * CDDL HEADER START 3 * 4 * The contents of this file are subject to the terms of the 5 * Common Development and Distribution License (the "License"). 6 * You may not use this file except in compliance with the License. 7 * 8 * See LICENSE.txt included in this distribution for the specific 9 * language governing permissions and limitations under the License. 10 * 11 * When distributing Covered Code, include this CDDL HEADER in each 12 * file and include the License file at LICENSE.txt. 13 * If applicable, add the following below this CDDL HEADER, with the 14 * fields enclosed by brackets "[]" replaced with your own identifying 15 * information: Portions Copyright [yyyy] [name of copyright owner] 16 * 17 * CDDL HEADER END 18 */ 19 20 /* 21 * Copyright (c) 2006, 2022, Oracle and/or its affiliates. All rights reserved. 22 */ 23 package org.opengrok.indexer.history; 24 25 import java.io.File; 26 import java.util.Date; 27 import java.util.Map; 28 29 import org.jetbrains.annotations.Nullable; 30 import org.opengrok.indexer.util.ForbiddenSymlinkException; 31 32 interface HistoryCache { 33 /** 34 * Create and initialize an empty history cache if one doesn't exist 35 * already. 36 * 37 * @throws HistoryException if initialization fails 38 */ initialize()39 void initialize() throws HistoryException; 40 41 /** 42 * Check whether this cache implementation can store history for the given 43 * repository. 44 * 45 * @param repository the repository to check 46 * @return {@code true} if this cache implementation can store history 47 * for the repository, or {@code false} otherwise 48 */ supportsRepository(Repository repository)49 boolean supportsRepository(Repository repository); 50 51 /** 52 * Retrieve the history for the given file, either from the cache or by 53 * parsing the history information in the repository. 54 * 55 * @param file The file to retrieve history for 56 * @param repository The external repository to read the history from (can be <code>null</code>) 57 * @param withFiles A flag saying whether the returned history should include a list of files 58 * touched by each changeset. If false, the implementation is allowed to skip the file list, 59 * but it doesn't have to. 60 * @throws HistoryException if the history cannot be fetched 61 * @throws ForbiddenSymlinkException if symbolic-link checking encounters 62 * an ineligible link 63 */ get(File file, @Nullable Repository repository, boolean withFiles)64 History get(File file, @Nullable Repository repository, boolean withFiles) 65 throws HistoryException, ForbiddenSymlinkException; 66 67 /** 68 * Store the history for a repository. 69 * 70 * @param history The history to store 71 * @param repository The repository whose history to store 72 * @throws HistoryException if the history cannot be stored 73 */ store(History history, Repository repository)74 void store(History history, Repository repository) throws HistoryException; 75 76 /** 77 * Store potentially partial history for a repository. 78 * 79 * @param history The history to store 80 * @param repository The repository whose history to store 81 * @param tillRevision end revision (can be null) 82 * @throws HistoryException if the history cannot be stored 83 */ store(History history, Repository repository, String tillRevision)84 void store(History history, Repository repository, String tillRevision) throws HistoryException; 85 86 /** 87 * Optimize how the history is stored on disk. This method is typically 88 * called after the cache has been populated, or after large modifications 89 * to the cache. The exact effect of this method is specific to each 90 * implementation, but it may for example include compressing, compacting 91 * or reordering the disk image of the cache in order to optimize 92 * performance or space usage. 93 * 94 * @throws HistoryException if an error happens during optimization 95 */ optimize()96 void optimize() throws HistoryException; 97 98 /** 99 * Check if the specified file is present in the cache. 100 * @param file the file to check 101 * @return {@code true} if the file is in the cache, {@code false} 102 * otherwise 103 */ hasCacheForFile(File file)104 boolean hasCacheForFile(File file) throws HistoryException; 105 106 /** 107 * Get the revision identifier for the latest cached revision in a repository. 108 * 109 * @param repository the repository whose latest revision to return 110 * @return a string representing the latest revision in the cache, 111 * or {@code null} if it is unknown 112 * @throws HistoryException on error 113 */ getLatestCachedRevision(Repository repository)114 String getLatestCachedRevision(Repository repository) throws HistoryException; 115 116 /** 117 * Get the last modified times for all files and subdirectories in the 118 * specified directory. 119 * 120 * @param directory which directory to fetch modification times for 121 * @param repository the repository in which the directory lives 122 * @return a map from file names to modification times 123 */ getLastModifiedTimes(File directory, Repository repository)124 Map<String, Date> getLastModifiedTimes(File directory, Repository repository) 125 throws HistoryException; 126 127 /** 128 * Clear the history cache for a repository. 129 * 130 * @param repository the repository whose cache to clear 131 * @throws HistoryException if the cache couldn't be cleared 132 */ clear(Repository repository)133 void clear(Repository repository) throws HistoryException; 134 135 /** 136 * Clear entry for single file from history cache. 137 * @param file path to the file relative to the source root 138 */ clearFile(String file)139 void clearFile(String file); 140 141 /** 142 * Get a string with information about the history cache. 143 * 144 * @return a free form text string describing the history cache instance 145 * @throws HistoryException if an error occurred while getting the info 146 */ getInfo()147 String getInfo() throws HistoryException; 148 } 149