001/*
002 * #%L
003 * Netarchivesuite - archive
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.archive.checksum;
024
025import java.io.File;
026import java.io.InputStream;
027
028import dk.netarkivet.common.distribute.RemoteFile;
029import dk.netarkivet.common.exceptions.ArgumentNotValid;
030import dk.netarkivet.common.exceptions.IOFailure;
031import dk.netarkivet.common.exceptions.IllegalState;
032
033/**
034 * This abstract class is the interface for the checksum archives, which can be one of the following: <br>
035 * - <b>FileChecksumArchive</b> where the archive is placed in a single file. <br>
036 * - <b>DatabaseChecksumArchive</b> where the archive is placed in a database. <br>
037 *
038 * @see dk.netarkivet.archive.checksum.FileChecksumArchive
039 */
040public interface ChecksumArchive {
041
042    /**
043     * Method for checking whether there is enough space left on the hard drive.
044     *
045     * @return Whether there is enough space left on the hard drive.
046     */
047    public boolean hasEnoughSpace();
048
049    /**
050     * Method for removing a bad entry from the archive. This finds the record and removes it if it has the incorrect
051     * checksum. The incorrect record is not deleted, but instead put into a backup file for all the incorrect records.
052     *
053     * @param filename The name of the file whose record should be removed.
054     * @param correctFile The correct remote file to replace the bad one in the archive.
055     * @return A file containing the removed data.
056     * @throws ArgumentNotValid If one of the arguments are not valid.
057     * @throws IOFailure If the entry cannot be corrected.
058     * @throws IllegalState If no such entry exists to be corrected, or if the entry has a different checksum than
059     * expected.
060     */
061    public File correct(String filename, File correctFile) throws IOFailure, ArgumentNotValid, IllegalState;
062
063    /**
064     * Method for retrieving the checksum of a specific entry in the archive.
065     *
066     * @param filename The name of the file entry in the archive for whom the checksum should be retrieved.
067     * @return The checksum of a record, or null if it was not found.
068     */
069    public String getChecksum(String filename);
070
071    /**
072     * Method for checking whether an entry exists within the archive.
073     *
074     * @param filename The name of the file whose entry in the archive should be determined.
075     * @return Whether an entry with the filename was found.
076     */
077    public boolean hasEntry(String filename);
078
079    /**
080     * Method for uploading a new file to the archive. The checksum of the file needs to be calculated before it is
081     * placed in the archive with the given filename.
082     *
083     * @param arcfile The remote file to be uploaded.
084     * @param filename The name of the file.
085     */
086    public void upload(RemoteFile arcfile, String filename);
087    
088    /**
089     * Upload a filename with a pre-computed checksum.
090     * @param checksum
091     * @param filename
092     */
093    public void upload(String checksum, String filename);
094    
095    /**
096     * Method for calculating the checksum of a specific file.
097     *
098     * @param f The file to calculate the checksum from.
099     * @return The checksum of the file.
100     */
101    public String calculateChecksum(File f);
102
103    /**
104     * Method for calculating the checksum when the file is received in the form of an inputstream.
105     *
106     * @param is The input stream to calculate the checksum from.
107     * @return The checksum of the inputstream.
108     */
109    public String calculateChecksum(InputStream is);
110
111    /**
112     * Method for retrieving the archive as a temporary file containing the checksum entries.
113     *
114     * @return A temporary checksum file.
115     */
116    public File getArchiveAsFile();
117
118    /**
119     * Method for retrieving the names of all the files within the archive as a temporary file.
120     *
121     * @return A temporary file containing the list of all the filenames. This file has one filename per line.
122     */
123    public File getAllFilenames();
124
125    /**
126     * Method for cleaning up when closing down.
127     */
128    public void cleanup();
129
130}