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 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 and Description
    --- | ---
    `static int` | `KIND_UNOFFICIAL` Bit flag indicating a checksum which is not part of the official repository layout/structure.

  - ### Method Summary

    Methods
    Modifier and Type | Method and 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` | `onNoMoreChecksums()` Signals that all available checksums have been processed.
    `boolean` | `onTransferChecksumFailure(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`.

- - ### Field Detail

    - #### KIND_UNOFFICIAL

          static final int KIND_UNOFFICIAL

      Bit flag indicating a checksum which is not part of the official repository layout/structure.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### 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.

Copyright © 2010-2014 The Eclipse Foundation. All Rights Reserved.