Package org.eclipse.aether.spi.connector.checksum

Interface ChecksumPolicy

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.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static enum 
    ChecksumPolicy.ChecksumKind
    Enum denoting origin of checksum.

  • Method Summary

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

  • Method Details

    • onChecksumMatch

      boolean onChecksumMatch(String algorithm, ChecksumPolicy.ChecksumKind 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 field providing further details about the checksum.
      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, ChecksumPolicy.ChecksumKind kind, org.eclipse.aether.transfer.ChecksumFailureException exception) throws org.eclipse.aether.transfer.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 field providing further details about the checksum.
      exception - The exception describing the checksum mismatch, must not be null.
      Throws:
      org.eclipse.aether.transfer.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, ChecksumPolicy.ChecksumKind kind, org.eclipse.aether.transfer.ChecksumFailureException exception) throws org.eclipse.aether.transfer.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 field providing further details about the checksum.
      exception - The exception describing the checksum error, must not be null.
      Throws:
      org.eclipse.aether.transfer.ChecksumFailureException - If the checksum validation is to be failed. If the method returns normally, validation continues with the next checksum.

    • onNoMoreChecksums

      void onNoMoreChecksums() throws org.eclipse.aether.transfer.ChecksumFailureException
      Signals that all available checksums have been processed.
      Throws:
      org.eclipse.aether.transfer.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(org.eclipse.aether.transfer.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, ChecksumKind, ChecksumFailureException), onChecksumError(String, ChecksumKind, ChecksumFailureException) or onNoMoreChecksums().
      Returns:
      true to accept the download nevertheless and let artifact resolution succeed, false to reject the transferred file as unusable.