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}