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.

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

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.