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 @Override 041 void close(); 042 043 /** 044 * Gets a single ARC record out of the ArcRepository. 045 * 046 * @param arcfile The name of a file containing the desired record. 047 * @param index The offset of the desired record in the file 048 * @return a BitarchiveRecord-object, or null if request times out or object is not found. 049 * @throws IOFailure If the get operation failed. 050 * @throws ArgumentNotValid if the given arcfile is null or empty string, or the given index is negative. 051 */ 052 @Override 053 BitarchiveRecord get(String arcfile, long index) throws ArgumentNotValid; 054 055 /** 056 * Retrieves a file from an ArcRepository and places it in a local file. 057 * 058 * @param arcfilename Name of the arcfile to retrieve. 059 * @param replica The bitarchive to retrieve the data from. On implementations with only one replica, null may be 060 * used. 061 * @param toFile Filename of a place where the file fetched can be put. 062 * @throws IOFailure if there are problems getting a reply or the file could not be found. 063 */ 064 @Override 065 void getFile(String arcfilename, Replica replica, File toFile); 066 067 /** 068 * Store the given file in the ArcRepository. After storing, the file is deleted. 069 * 070 * @param file A file to be stored. Must exist. 071 * @throws IOFailure thrown if store is unsuccessful, or failed to clean up files after the store operation. 072 * @throws ArgumentNotValid if file parameter is null or file is not an existing file. 073 */ 074 @Override 075 void store(File file) throws IOFailure, ArgumentNotValid; 076 077 /** 078 * Runs a batch batch job on each file in the ArcRepository. 079 * 080 * @param job An object that implements the FileBatchJob interface. The initialize() method will be called before 081 * processing and the finish() method will be called afterwards. The process() method will be called with each File 082 * entry. An optional function postProcess() allows handling the combined results of the batchjob, e.g. summing the 083 * results, sorting, etc. 084 * @param replicaId The archive to execute the job on. 085 * @param args The arguments for the batchjob. 086 * @return The status of the batch job after it ended. 087 */ 088 BatchStatus batch(FileBatchJob job, String replicaId, String... args); 089 090 /** 091 * Updates the administrative data in the ArcRepository for a given file and replica. 092 * 093 * @param fileName The name of a file stored in the ArcRepository. 094 * @param bitarchiveId The id of the replica that the administrative data for fileName is wrong for. 095 * @param newval What the administrative data will be updated to. 096 */ 097 @Override 098 @Deprecated 099 void updateAdminData(String fileName, String bitarchiveId, ReplicaStoreState newval); 100 101 /** 102 * Updates the checksum kept in the ArcRepository for a given file. It is the responsibility of the ArcRepository 103 * implementation to ensure that this checksum matches that of the underlying files. 104 * 105 * @param filename The name of a file stored in the ArcRepository. 106 * @param checksum The new checksum. 107 */ 108 @Override 109 @Deprecated 110 void updateAdminChecksum(String filename, String checksum); 111 112 /** 113 * Remove a file from one part of the ArcRepository, retrieving a copy for security purposes. This is typically used 114 * when repairing a file that has been corrupted. 115 * 116 * @param fileName The name of the file to remove. 117 * @param bitarchiveId The id of the replica from which to remove the file. 118 * @param checksum The checksum of the file to be removed. 119 * @param credentials A string that shows that the user is allowed to perform this operation. 120 * @return A local copy of the file removed. 121 */ 122 @Override 123 @Deprecated 124 File removeAndGetFile(String fileName, String bitarchiveId, String checksum, String credentials); 125 126}