1 package org.eclipse.aether.spi.connector.checksum; 2 3 /* 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the 9 * "License"); you may not use this file except in compliance 10 * with the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, 15 * software distributed under the License is distributed on an 16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17 * KIND, either express or implied. See the License for the 18 * specific language governing permissions and limitations 19 * under the License. 20 */ 21 22 import org.eclipse.aether.transfer.ChecksumFailureException; 23 24 /** 25 * A checksum policy gets employed by repository connectors to validate the integrity of a downloaded file. For each 26 * downloaded file, a checksum policy instance is obtained and presented with the available checksums to conclude 27 * whether the download is valid or not. The following pseudo-code illustrates the usage of a checksum policy by a 28 * repository connector in some more detail (the retry logic has been omitted for the sake of brevity): 29 * 30 * <pre> 31 * void validateChecksums() throws ChecksumFailureException { 32 * for (checksum : checksums) { 33 * switch (checksum.state) { 34 * case MATCH: 35 * if (policy.onChecksumMatch(...)) { 36 * return; 37 * } 38 * break; 39 * case MISMATCH: 40 * policy.onChecksumMismatch(...); 41 * break; 42 * case ERROR: 43 * policy.onChecksumError(...); 44 * break; 45 * } 46 * } 47 * policy.onNoMoreChecksums(); 48 * } 49 * 50 * void downloadFile() throws Exception { 51 * ... 52 * policy = newChecksumPolicy(); 53 * try { 54 * validateChecksums(); 55 * } catch (ChecksumFailureException e) { 56 * if (!policy.onTransferChecksumFailure(...)) { 57 * throw e; 58 * } 59 * } 60 * } 61 * </pre> 62 * 63 * Checksum policies might be stateful and are generally not thread-safe. 64 */ 65 public interface ChecksumPolicy 66 { 67 68 /** 69 * Bit flag indicating a checksum which is not part of the official repository layout/structure. 70 */ 71 int KIND_UNOFFICIAL = 0x01; 72 73 /** 74 * Signals a match between the locally computed checksum value and the checksum value declared by the remote 75 * repository. 76 * 77 * @param algorithm The name of the checksum algorithm being used, must not be {@code null}. 78 * @param kind A bit field providing further details about the checksum. See the {@code KIND_*} constants in this 79 * interface for possible bit flags. 80 * @return {@code true} to accept the download as valid and stop further validation, {@code false} to continue 81 * validation with the next checksum. 82 */ 83 boolean onChecksumMatch( String algorithm, int kind ); 84 85 /** 86 * Signals a mismatch between the locally computed checksum value and the checksum value declared by the remote 87 * repository. A simple policy would just rethrow the provided exception. More sophisticated policies could update 88 * their internal state and defer a conclusion until all available checksums have been processed. 89 * 90 * @param algorithm The name of the checksum algorithm being used, must not be {@code null}. 91 * @param kind A bit field providing further details about the checksum. See the {@code KIND_*} constants in this 92 * interface for possible bit flags. 93 * @param exception The exception describing the checksum mismatch, must not be {@code null}. 94 * @throws ChecksumFailureException If the checksum validation is to be failed. If the method returns normally, 95 * validation continues with the next checksum. 96 */ 97 void onChecksumMismatch( String algorithm, int kind, ChecksumFailureException exception ) 98 throws ChecksumFailureException; 99 100 /** 101 * Signals an error while computing the local checksum value or retrieving the checksum value from the remote 102 * repository. 103 * 104 * @param algorithm The name of the checksum algorithm being used, must not be {@code null}. 105 * @param kind A bit field providing further details about the checksum. See the {@code KIND_*} constants in this 106 * interface for possible bit flags. 107 * @param exception The exception describing the checksum error, must not be {@code null}. 108 * @throws ChecksumFailureException If the checksum validation is to be failed. If the method returns normally, 109 * validation continues with the next checksum. 110 */ 111 void onChecksumError( String algorithm, int kind, ChecksumFailureException exception ) 112 throws ChecksumFailureException; 113 114 /** 115 * Signals that all available checksums have been processed. 116 * 117 * @throws ChecksumFailureException If the checksum validation is to be failed. If the method returns normally, the 118 * download is assumed to be valid. 119 */ 120 void onNoMoreChecksums() 121 throws ChecksumFailureException; 122 123 /** 124 * Signals that the download is being retried after a previously thrown {@link ChecksumFailureException} that is 125 * {@link ChecksumFailureException#isRetryWorthy() retry-worthy}. Policies that maintain internal state will usually 126 * have to reset some of this state at this point to prepare for a new round of validation. 127 */ 128 void onTransferRetry(); 129 130 /** 131 * Signals that (even after a potential retry) checksum validation has failed. A policy could opt to merely log this 132 * issue or insist on rejecting the downloaded file as unusable. 133 * 134 * @param exception The exception that was thrown from a prior call to 135 * {@link #onChecksumMismatch(String, int, ChecksumFailureException)}, 136 * {@link #onChecksumError(String, int, ChecksumFailureException)} or {@link #onNoMoreChecksums()}. 137 * @return {@code true} to accept the download nevertheless and let artifact resolution succeed, {@code false} to 138 * reject the transferred file as unusable. 139 */ 140 boolean onTransferChecksumFailure( ChecksumFailureException exception ); 141 142 }