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.arcrepository.bitpreservation;
024
025import java.util.List;
026
027import dk.netarkivet.common.distribute.arcrepository.Replica;
028
029/**
030 * The interface for the preservations states used by the web applications.
031 */
032public interface PreservationState {
033    /**
034     * Get the checksum of this file in a specific replica.
035     *
036     * @param replica The replica to get the checksum from.
037     * @return The file's checksum, if it is present in the replica, or "" if it either is absent or an error occurred.
038     */
039    List<String> getReplicaChecksum(Replica replica);
040
041    /**
042     * Get the MD5 checksum stored in the admin data.
043     *
044     * @return Checksum value as found in the admin data given at creation.
045     */
046    String getAdminChecksum();
047
048    /**
049     * Get the status of the file in a bitarchive, according to the admin data. This returns the status as a string for
050     * presentation purposes only. TODO Needs localisation.
051     *
052     * @param replica The replica to get status for
053     * @return Status that the admin data knows for this file in the bitarchive.
054     */
055    String getAdminReplicaState(Replica replica);
056
057    /**
058     * Check if the admin data reflect the actual status of the archive.
059     * <p>
060     * Admin State checking: For each bitarchive the admin state is compared to the checksum received from the
061     * bitarchive.
062     * <p>
063     * If no checksum is received from the bitarchive the valid admin states are UPLOAD_STARTED and UPLOAD_FAILED. If a
064     * checksum is received from the bitarchive the valid admin state is UPLOAD_COMPLETED Admin checksum checking: The
065     * admin checksum must match the majority of reported checksums.
066     * <p>
067     * Notice that a valid Admin data record does NOT imply that everything is ok. Specifically a file may be missing
068     * from a bitarchive, or the checksum of a file in a bitarchive may be wrong.
069     *
070     * @return true, if admin data match the state of the bitarchives, false otherwise
071     */
072    boolean isAdminDataOk();
073
074    /**
075     * Returns a reference to a bitarchive that contains a version of the file with the correct checksum.
076     * <p>
077     * The correct checksum is defined as the checksum that the majority of the bitarchives and admin data agree upon.
078     * <p>
079     * If no bitarchive exists with a correct version of the file null is returned.
080     *
081     * @return the name of the reference bitarchive or null if no reference exists
082     */
083    Replica getReferenceBitarchive();
084
085    /**
086     * Get a checksum that the whole bitarchive agrees upon, or else "".
087     *
088     * @param replica A replica to get checksum for this file from
089     * @return The checksum for this file in the replica, if all machines that have that file agree, otherwise "". If no
090     * checksums are found, also returns "".
091     */
092    String getUniqueChecksum(Replica replica);
093
094    /**
095     * Check if the file is missing from a bitarchive.
096     *
097     * @param bitarchive the bitarchive to check
098     * @return true if the file is missing from the bitarchive
099     */
100    boolean fileIsMissing(Replica bitarchive);
101
102    /**
103     * Retrieve checksum that the majority of checksum references (bitarchives+admin) agree upon.
104     *
105     * @return the reference checksum or "" if no majority exists
106     */
107    String getReferenceCheckSum();
108
109    /**
110     * Returns true if the checksum reported by admin data is equal to the majority checksum. If no majority checksum
111     * exists true is also returned. When this method returns false it is possible to correct the admin checksum using
112     * the majority checksum - when true is returned no better checksum exists for admin data.
113     *
114     * @return true, if the checksum reported by admin data is equal to the majority checksum
115     */
116    boolean isAdminCheckSumOk();
117
118    /**
119     * Returns a human-readable representation of this object. Do not depend on this format for anything automated, as
120     * it may change at any time.
121     *
122     * @return Description of this object.
123     */
124    String toString();
125
126    /**
127     * Get the filename, this FilePreservationState is about. Needed to get at the filename given to constructor, and
128     * allow for a better datastructure.
129     *
130     * @return the filename
131     */
132    String getFilename();
133}