001/*
002 * #%L
003 * Netarchivesuite - archive
004 * %%
005 * Copyright (C) 2005 - 2018 The Royal Danish Library, 
006 *             the National Library of France and the Austrian National Library.
007 * %%
008 * This program is free software: you can redistribute it and/or modify
009 * it under the terms of the GNU Lesser General Public License as
010 * published by the Free Software Foundation, either version 2.1 of the
011 * License, or (at your option) any later version.
012 * 
013 * This program is distributed in the hope that it will be useful,
014 * but WITHOUT ANY WARRANTY; without even the implied warranty of
015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016 * GNU General Lesser Public License for more details.
017 * 
018 * You should have received a copy of the GNU General Lesser Public
019 * License along with this program.  If not, see
020 * <http://www.gnu.org/licenses/lgpl-2.1.html>.
021 * #L%
022 */
023package dk.netarkivet.archive.arcrepository.bitpreservation;
024
025import java.util.Date;
026import java.util.Map;
027
028import dk.netarkivet.common.distribute.arcrepository.Replica;
029
030/**
031 * All bitpreservation implementations are assumed to have access to admin data and bitarchives. Operations may request
032 * information from the bitarchive by sending batch jobs, reading admin data directly, or reading from cached
033 * information from either.
034 */
035public interface ActiveBitPreservation {
036    // General state
037
038    /**
039     * Get details of the state of one or more files in the bitarchives and admin data.
040     *
041     * @param filenames the list of filenames to investigate
042     * @return a map ([filename]-> [FilePreservationState]) with the preservationstate of all files in the list. The
043     * preservationstates in the map will be null for all filenames, that are not found in admin data.
044     */
045    Map<String, PreservationState> getPreservationStateMap(String... filenames);
046
047    /**
048     * Get the details of the state of the given file in the bitarchives and admin data.
049     *
050     * @param filename A given file
051     * @return the FilePreservationState for the given file. This will be null, if the filename is not found in admin
052     * data.
053     */
054    PreservationState getPreservationState(String filename);
055
056    // Check state for bitarchives
057
058    /**
059     * Return a list of files marked as missing on this replica. A file is considered missing if it exists in admin
060     * data, but is not known in the bit archives. Guaranteed not to recheck the archive, simply returns the list
061     * generated by the last test.
062     *
063     * @param replica The replica to get missing files from.
064     * @return A list of missing files.
065     */
066    Iterable<String> getMissingFiles(Replica replica);
067
068    /**
069     * Return a list of files with changed checksums on this replica. A file is considered changed if checksum does not
070     * compare to admin data. Guaranteed not to recheck the archive, simply returns the list generated by the last test.
071     *
072     * @param replica The replica to get a list of changed files from.
073     * @return A list of files with changed checksums.
074     */
075    Iterable<String> getChangedFiles(Replica replica);
076
077    /**
078     * Update the list of files in a given bitarchive. This will be used for the next call to getMissingFiles.
079     *
080     * @param replica The replica to update list of files for.
081     */
082    void findMissingFiles(Replica replica);
083
084    /**
085     * Update the list of checksums in a given replica. This will be used for the next call to getChangedFiles.
086     *
087     * @param replica The replica to update list of files for.
088     */
089    void findChangedFiles(Replica replica);
090
091    /**
092     * Return the number of missing files for replica. Guaranteed not to recheck the archive, simply returns the number
093     * generated by the last test.
094     *
095     * @param replica The replica to get the number of missing files from.
096     * @return The number of missing files.
097     */
098    long getNumberOfMissingFiles(Replica replica);
099
100    /**
101     * Return the number of changed files for replica. Guaranteed not to recheck the archive, simply returns the number
102     * generated by the last test.
103     *
104     * @param replica The replica to get the number of changed files from.
105     * @return The number of changed files.
106     */
107    long getNumberOfChangedFiles(Replica replica);
108
109    /**
110     * Return the total number of files for replica. Guaranteed not to recheck the archive, simply returns the number
111     * generated by the last update.
112     *
113     * @param replica The replica to get the number of files from.
114     * @return The number of files.
115     */
116    long getNumberOfFiles(Replica replica);
117
118    /**
119     * Return the date for last check of missing files for replica. Guaranteed not to recheck the archive, simply
120     * returns the date for the last test.
121     *
122     * @param replica The replica to get date for changed files from.
123     * @return The date for last check of missing files.
124     */
125    Date getDateForMissingFiles(Replica replica);
126
127    /**
128     * Return the date for last check of changed files for replica. Guaranteed not to recheck the archive, simply
129     * returns the date for the last test.
130     *
131     * @param replica The replica to get date for changed files from.
132     * @return The date for last check of changed files.
133     */
134    Date getDateForChangedFiles(Replica replica);
135
136    // Update files in bitarchives
137
138    /**
139     * Check that files are indeed missing on the given replica, and present in admin data and reference replica. If so,
140     * upload missing files from reference replica to this replica.
141     *
142     * @param replica The replica to restore files to
143     * @param filenames The names of the files.
144     */
145    void uploadMissingFiles(Replica replica, String... filenames);
146
147    /**
148     * Check that the checksum of the file is indeed different to the value in admin data and reference replica. If so,
149     * remove missing file and upload it from reference replica to this replica.
150     *
151     * @param replica The replica to restore file to
152     * @param filename The name of the file
153     * @param credentials The credentials used to perform this replace operation
154     * @param checksum The known bad checksum. Only a file with this bad checksum is attempted repaired.
155     */
156    void replaceChangedFile(Replica replica, String filename, String credentials, String checksum);
157
158    // Check state for admin data
159
160    /**
161     * Return a list of files represented in replica but missing in AdminData.
162     *
163     * @return A list of missing files.
164     */
165    Iterable<String> getMissingFilesForAdminData();
166
167    /**
168     * Return a list of files with wrong checksum or state in admin data.
169     *
170     * @return A list of files with wrong checksum or state.
171     */
172    Iterable<String> getChangedFilesForAdminData();
173
174    // Update admin data
175
176    /**
177     * Add files unknown in admin.data to admin.data.
178     *
179     * @param filenames The files to add.
180     */
181    void addMissingFilesToAdminData(String... filenames);
182
183    /**
184     * Reestablish admin data to match bitarchive states for file.
185     *
186     * @param filename The file to reestablish state for.
187     */
188    void changeStateForAdminData(String filename);
189}