001/* 002 * #%L 003 * Netarchivesuite - common 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 */ 023 024package dk.netarkivet.common.distribute.arcrepository; 025 026import java.io.File; 027 028import dk.netarkivet.common.exceptions.ArgumentNotValid; 029import dk.netarkivet.common.exceptions.IOFailure; 030import dk.netarkivet.common.utils.batch.FileBatchJob; 031 032/** 033 * Generic interface defining all methods that an ArcRepository provides. Typically, an application using this will only 034 * see one of the restricted superinterfaces. 035 */ 036public interface ArcRepositoryClient extends HarvesterArcRepositoryClient, ViewerArcRepositoryClient, 037 PreservationArcRepositoryClient { 038 039 /** Call on shutdown to release external resources. */ 040 void close(); 041 042 /** 043 * Gets a single ARC record out of the ArcRepository. 044 * 045 * @param arcfile The name of a file containing the desired record. 046 * @param index The offset of the desired record in the file 047 * @return a BitarchiveRecord-object, or null if request times out or object is not found. 048 * @throws IOFailure If the get operation failed. 049 * @throws ArgumentNotValid if the given arcfile is null or empty string, or the given index is negative. 050 */ 051 BitarchiveRecord get(String arcfile, long index) throws ArgumentNotValid; 052 053 /** 054 * Retrieves a file from an ArcRepository and places it in a local file. 055 * 056 * @param arcfilename Name of the arcfile to retrieve. 057 * @param replica The bitarchive to retrieve the data from. On implementations with only one replica, null may be 058 * used. 059 * @param toFile Filename of a place where the file fetched can be put. 060 * @throws IOFailure if there are problems getting a reply or the file could not be found. 061 */ 062 void getFile(String arcfilename, Replica replica, File toFile); 063 064 /** 065 * Store the given file in the ArcRepository. After storing, the file is deleted. 066 * 067 * @param file A file to be stored. Must exist. 068 * @throws IOFailure thrown if store is unsuccessful, or failed to clean up files after the store operation. 069 * @throws ArgumentNotValid if file parameter is null or file is not an existing file. 070 */ 071 void store(File file) throws IOFailure, ArgumentNotValid; 072 073 /** 074 * Runs a batch batch job on each file in the ArcRepository. 075 * 076 * @param job An object that implements the FileBatchJob interface. The initialize() method will be called before 077 * processing and the finish() method will be called afterwards. The process() method will be called with each File 078 * entry. An optional function postProcess() allows handling the combined results of the batchjob, e.g. summing the 079 * results, sorting, etc. 080 * @param replicaId The archive to execute the job on. 081 * @param args The arguments for the batchjob. 082 * @return The status of the batch job after it ended. 083 */ 084 BatchStatus batch(FileBatchJob job, String replicaId, String... args); 085 086 /** 087 * Updates the administrative data in the ArcRepository for a given file and replica. 088 * 089 * @param fileName The name of a file stored in the ArcRepository. 090 * @param bitarchiveId The id of the replica that the administrative data for fileName is wrong for. 091 * @param newval What the administrative data will be updated to. 092 */ 093 void updateAdminData(String fileName, String bitarchiveId, ReplicaStoreState newval); 094 095 /** 096 * Updates the checksum kept in the ArcRepository for a given file. It is the responsibility of the ArcRepository 097 * implementation to ensure that this checksum matches that of the underlying files. 098 * 099 * @param filename The name of a file stored in the ArcRepository. 100 * @param checksum The new checksum. 101 */ 102 void updateAdminChecksum(String filename, String checksum); 103 104 /** 105 * Remove a file from one part of the ArcRepository, retrieving a copy for security purposes. This is typically used 106 * when repairing a file that has been corrupted. 107 * 108 * @param fileName The name of the file to remove. 109 * @param bitarchiveId The id of the replica from which to remove the file. 110 * @param checksum The checksum of the file to be removed. 111 * @param credentials A string that shows that the user is allowed to perform this operation. 112 * @return A local copy of the file removed. 113 */ 114 File removeAndGetFile(String fileName, String bitarchiveId, String checksum, String credentials); 115 116}