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