001/* 002 * #%L 003 * Netarchivesuite - common 004 * %% 005 * Copyright (C) 2005 - 2014 The Royal Danish Library, the Danish State and University 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.common.distribute.arcrepository; 024 025import java.io.File; 026 027import dk.netarkivet.common.exceptions.ArgumentNotValid; 028import dk.netarkivet.common.exceptions.IOFailure; 029import dk.netarkivet.common.utils.batch.FileBatchJob; 030 031/** 032 * Implements the Facade pattern to shield off the methods in JMSArcRepositoryClient not to be used by the bit 033 * preservation system. 034 */ 035public interface PreservationArcRepositoryClient { 036 037 /** Call on shutdown to release external resources. */ 038 void close(); 039 040 /** 041 * Gets a single ARC record out of the ArcRepository. 042 * 043 * @param arcfile The name of a file containing the desired record. 044 * @param index The offset of the desired record in the file 045 * @return a BitarchiveRecord-object, or null if request times out or object is not found. 046 * @throws ArgumentNotValid If the get operation failed. 047 */ 048 BitarchiveRecord get(String arcfile, long index) throws ArgumentNotValid; 049 050 /** 051 * Retrieves a file from an ArcRepository and places it in a local file. 052 * 053 * @param arcfilename Name of the arcfile to retrieve. 054 * @param replica The bitarchive to retrieve the data from. 055 * @param toFile Filename of a place where the file fetched can be put. 056 * @throws IOFailure if there are problems getting a reply or the file could not be found. 057 */ 058 void getFile(String arcfilename, Replica replica, File toFile); 059 060 /** 061 * Store the given file in the ArcRepository. After storing, the file is deleted. 062 * 063 * @param file A file to be stored. Must exist. 064 * @throws IOFailure thrown if store is unsuccessful, or failed to clean up files after the store operation. 065 * @throws ArgumentNotValid if file parameter is null or file is not an existing file. 066 */ 067 void store(File file) throws IOFailure, ArgumentNotValid; 068 069 /** 070 * Runs a batch batch job on each file in the ArcRepository. 071 * 072 * @param job An object that implements the FileBatchJob interface. The initialize() method will be called before 073 * processing and the finish() method will be called afterwards. The process() method will be called with each File 074 * entry. An optional function postProcess() allows handling the combined results of the batchjob, e.g. summing the 075 * results, sorting, etc. 076 * @param replicaId The archive to execute the job on. 077 * @param args The arguments for the batchjob. 078 * @return The status of the batch job after it ended. 079 */ 080 BatchStatus batch(FileBatchJob job, String replicaId, String... args); 081 082 /** 083 * Updates the administrative data in the ArcRepository for a given file and bitarchive replica. 084 * 085 * @param fileName The name of a file stored in the ArcRepository. 086 * @param replicaId The id if the replica that the administrative data for fileName is wrong for. 087 * @param newval What the administrative data will be updated to. 088 */ 089 void updateAdminData(String fileName, String replicaId, ReplicaStoreState newval); 090 091 /** 092 * Updates the checksum kept in the ArcRepository for a given file. It is the responsibility of the ArcRepository 093 * implementation to ensure that this checksum matches that of the underlying files. 094 * 095 * @param filename The name of a file stored in the ArcRepository. 096 * @param checksum The new checksum. 097 */ 098 void updateAdminChecksum(String filename, String checksum); 099 100 /** 101 * Remove a file from one part of the ArcRepository, retrieving a copy for security purposes. This is typically used 102 * when repairing a file that has been corrupted. 103 * 104 * @param fileName The name of the file to remove. 105 * @param replicaId The replica id from which to remove the file. 106 * @param checksum The checksum of the file to be removed. 107 * @param credentials A string that shows that the user is allowed to perform this operation. 108 * @return A local copy of the file removed. 109 */ 110 File removeAndGetFile(String fileName, String replicaId, String checksum, String credentials); 111 112 /** 113 * Retrieves all the checksum from the replica through a GetAllChecksumMessage. 114 * <p> 115 * This is the checksum archive alternative to running a ChecksumBatchJob. 116 * 117 * @param replicaId The id of the replica from which the checksums should be retrieved. 118 * @return A list of ChecksumEntries which is the results of the GetAllChecksumMessage. 119 * @see dk.netarkivet.archive.checksum.distribute.GetAllChecksumsMessage 120 */ 121 File getAllChecksums(String replicaId); 122 123 /** 124 * Retrieves the checksum of a specific file. 125 * <p> 126 * This is the checksum archive alternative to running a ChecksumJob limited to a specific file. 127 * 128 * @param replicaId The name of the replica to send the message. 129 * @param filename The name of the file for whom the checksum should be retrieved. 130 * @return The checksum of the file in the replica. Or null if an error occurred. 131 */ 132 String getChecksum(String replicaId, String filename); 133 134 /** 135 * Retrieves the names of all the files in the replica through a GetAllFilenamesMessage. 136 * <p> 137 * This is the checksum archive alternative to running a FilelistBatchJob. 138 * 139 * @param replicaId The id of the replica from which the list of filenames should be retrieved. 140 * @return A list of all the filenames within the archive of the given replica. 141 * @see dk.netarkivet.archive.checksum.distribute.GetAllFilenamesMessage 142 */ 143 File getAllFilenames(String replicaId); 144 145 /** 146 * Method for correcting a file in a replica. 147 * <p> 148 * This is the checksum archive method for correcting a file entry in the archive. The bitarchive uses 149 * 'removeAndGetFile' followed by a 'store'. 150 * 151 * @param replicaId The identification of the replica. 152 * @param checksum The checksum of the corrupt entry in the archive. It is important to validate that the checksum 153 * actually is wrong before correcting the entry. 154 * @param file The new file to replace the old one. 155 * @param credentials The password for allowing to remove a file entry in the archive. 156 * @return The corrupted file from the archive. 157 */ 158 File correct(String replicaId, String checksum, File file, String credentials); 159 160}