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 and Description
static class	ChecksumPolicy.ChecksumKind Enum denoting origin of checksum.

Method Summary

Modifier and Type	Method and 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 Detail

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.