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 class  ChecksumPolicy.ChecksumKind
      Enum denoting origin of checksum.
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void onChecksumError​(java.lang.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​(java.lang.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​(java.lang.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 Detail

      • onChecksumMatch

        boolean onChecksumMatch​(java.lang.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​(java.lang.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​(java.lang.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.