package org.eclipse.aether.spi.connector.checksum;
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
import org.eclipse.aether.transfer.ChecksumFailureException;
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.
/**
* 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):
*
* <pre>
* 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;
* }
* }
* }
* </pre>
*
* Checksum policies might be stateful and are generally not thread-safe.
*/
public interface ChecksumPolicy
{
Bit flag indicating a checksum which is not part of the official repository layout/structure.
/**
* Bit flag indicating a checksum which is not part of the official repository layout/structure.
*/
int KIND_UNOFFICIAL = 0x01;
Signals a match between the locally computed checksum value and the checksum value declared by the remote
repository.
Params: - 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.
/**
* Signals a match between the locally computed checksum value and the checksum value declared by the remote
* repository.
*
* @param algorithm The name of the checksum algorithm being used, must not be {@code null}.
* @param kind A bit field providing further details about the checksum. See the {@code KIND_*} constants in this
* interface for possible bit flags.
* @return {@code true} to accept the download as valid and stop further validation, {@code false} to continue
* validation with the next checksum.
*/
boolean onChecksumMatch( String algorithm, int kind );
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.
Params: - 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.
/**
* 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.
*
* @param algorithm The name of the checksum algorithm being used, must not be {@code null}.
* @param kind A bit field providing further details about the checksum. See the {@code KIND_*} constants in this
* interface for possible bit flags.
* @param exception The exception describing the checksum mismatch, must not be {@code null}.
* @throws ChecksumFailureException If the checksum validation is to be failed. If the method returns normally,
* validation continues with the next checksum.
*/
void onChecksumMismatch( 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.
Params: - 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.
/**
* Signals an error while computing the local checksum value or retrieving the checksum value from the remote
* repository.
*
* @param algorithm The name of the checksum algorithm being used, must not be {@code null}.
* @param kind A bit field providing further details about the checksum. See the {@code KIND_*} constants in this
* interface for possible bit flags.
* @param exception The exception describing the checksum error, must not be {@code null}.
* @throws ChecksumFailureException If the checksum validation is to be failed. If the method returns normally,
* validation continues with the next checksum.
*/
void onChecksumError( String algorithm, int kind, ChecksumFailureException exception )
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.
/**
* 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.
*/
void onNoMoreChecksums()
throws ChecksumFailureException;
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. /**
* Signals that the download is being retried after a previously thrown {@link ChecksumFailureException} that is
* {@link ChecksumFailureException#isRetryWorthy() 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.
*/
void onTransferRetry();
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.
Params: - 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.
/**
* 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.
*
* @param exception The exception that was thrown from a prior call to
* {@link #onChecksumMismatch(String, int, ChecksumFailureException)},
* {@link #onChecksumError(String, int, ChecksumFailureException)} or {@link #onNoMoreChecksums()}.
* @return {@code true} to accept the download nevertheless and let artifact resolution succeed, {@code false} to
* reject the transferred file as unusable.
*/
boolean onTransferChecksumFailure( ChecksumFailureException exception );
}