Interface ChecksumPolicy

All Known Implementing Classes:
AbstractChecksumPolicy, FailChecksumPolicy, WarnChecksumPolicy

public interface ChecksumPolicy
A checksum policy gets employed by repository connectors to validate the integrity of a downloaded file. For each downloaded file, a checksum policy instance is obtained and presented with the available checksums to conclude whether the download is valid or not. The following pseudo-code illustrates the usage of a checksum policy by a repository connector in some more detail (the retry logic has been omitted for the sake of brevity):
 void validateChecksums() throws ChecksumFailureException {
   for (checksum : checksums) {
     switch (checksum.state) {
       case MATCH:
         if (policy.onChecksumMatch(...)) {
           return;
         }
         break;
       case MISMATCH:
         policy.onChecksumMismatch(...);
         break;
       case ERROR:
         policy.onChecksumError(...);
         break;
     }
   }
   policy.onNoMoreChecksums();
 }
 
 void downloadFile() throws Exception {
   ...
   policy = newChecksumPolicy();
   try {
     validateChecksums();
   } catch (ChecksumFailureException e) {
     if (!policy.onTransferChecksumFailure(...)) {
       throw e;
     }
   }
 }
 
Checksum policies might be stateful and are generally not thread-safe.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    Bit flag indicating a checksum which is not part of the official repository layout/structure.
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    onChecksumError(String algorithm, int kind, ChecksumFailureException exception)
    Signals an error while computing the local checksum value or retrieving the checksum value from the remote repository.
    boolean
    onChecksumMatch(String algorithm, int kind)
    Signals a match between the locally computed checksum value and the checksum value declared by the remote repository.
    void
    onChecksumMismatch(String algorithm, int kind, ChecksumFailureException exception)
    Signals a mismatch between the locally computed checksum value and the checksum value declared by the remote repository.
    void
    Signals that all available checksums have been processed.
    boolean
    Signals that (even after a potential retry) checksum validation has failed.
    void
    Signals that the download is being retried after a previously thrown ChecksumFailureException that is retry-worthy.
  • Field Details

    • KIND_UNOFFICIAL

      static final int KIND_UNOFFICIAL
      Bit flag indicating a checksum which is not part of the official repository layout/structure.
      See Also:
  • Method Details

    • onChecksumMatch

      boolean onChecksumMatch(String algorithm, int kind)
      Signals a match between the locally computed checksum value and the checksum value declared by the remote repository.
      Parameters:
      algorithm - The name of the checksum algorithm being used, must not be null.
      kind - A bit field providing further details about the checksum. See the KIND_* constants in this interface for possible bit flags.
      Returns:
      true to accept the download as valid and stop further validation, false to continue validation with the next checksum.
    • onChecksumMismatch

      void onChecksumMismatch(String algorithm, int kind, ChecksumFailureException exception) throws ChecksumFailureException
      Signals a mismatch between the locally computed checksum value and the checksum value declared by the remote repository. A simple policy would just rethrow the provided exception. More sophisticated policies could update their internal state and defer a conclusion until all available checksums have been processed.
      Parameters:
      algorithm - The name of the checksum algorithm being used, must not be null.
      kind - A bit field providing further details about the checksum. See the KIND_* constants in this interface for possible bit flags.
      exception - The exception describing the checksum mismatch, must not be null.
      Throws:
      ChecksumFailureException - If the checksum validation is to be failed. If the method returns normally, validation continues with the next checksum.
    • onChecksumError

      void onChecksumError(String algorithm, int kind, ChecksumFailureException exception) throws ChecksumFailureException
      Signals an error while computing the local checksum value or retrieving the checksum value from the remote repository.
      Parameters:
      algorithm - The name of the checksum algorithm being used, must not be null.
      kind - A bit field providing further details about the checksum. See the KIND_* constants in this interface for possible bit flags.
      exception - The exception describing the checksum error, must not be null.
      Throws:
      ChecksumFailureException - If the checksum validation is to be failed. If the method returns normally, validation continues with the next checksum.
    • onNoMoreChecksums

      void onNoMoreChecksums() throws ChecksumFailureException
      Signals that all available checksums have been processed.
      Throws:
      ChecksumFailureException - If the checksum validation is to be failed. If the method returns normally, the download is assumed to be valid.
    • onTransferRetry

      void onTransferRetry()
      Signals that the download is being retried after a previously thrown ChecksumFailureException that is retry-worthy. Policies that maintain internal state will usually have to reset some of this state at this point to prepare for a new round of validation.
    • onTransferChecksumFailure

      boolean onTransferChecksumFailure(ChecksumFailureException exception)
      Signals that (even after a potential retry) checksum validation has failed. A policy could opt to merely log this issue or insist on rejecting the downloaded file as unusable.
      Parameters:
      exception - The exception that was thrown from a prior call to onChecksumMismatch(String, int, ChecksumFailureException), onChecksumError(String, int, ChecksumFailureException) or onNoMoreChecksums().
      Returns:
      true to accept the download nevertheless and let artifact resolution succeed, false to reject the transferred file as unusable.