001package org.eclipse.aether.spi.connector.checksum; 002 003/* 004 * Licensed to the Apache Software Foundation (ASF) under one 005 * or more contributor license agreements. See the NOTICE file 006 * distributed with this work for additional information 007 * regarding copyright ownership. The ASF licenses this file 008 * to you under the Apache License, Version 2.0 (the 009 * "License"); you may not use this file except in compliance 010 * with the License. You may obtain a copy of the License at 011 * 012 * http://www.apache.org/licenses/LICENSE-2.0 013 * 014 * Unless required by applicable law or agreed to in writing, 015 * software distributed under the License is distributed on an 016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 017 * KIND, either express or implied. See the License for the 018 * specific language governing permissions and limitations 019 * under the License. 020 */ 021 022import org.eclipse.aether.transfer.ChecksumFailureException; 023 024/** 025 * A checksum policy gets employed by repository connectors to validate the integrity of a downloaded file. For each 026 * downloaded file, a checksum policy instance is obtained and presented with the available checksums to conclude 027 * whether the download is valid or not. The following pseudo-code illustrates the usage of a checksum policy by a 028 * repository connector in some more detail (the retry logic has been omitted for the sake of brevity): 029 * 030 * <pre> 031 * void validateChecksums() throws ChecksumFailureException { 032 * for (checksum : checksums) { 033 * switch (checksum.state) { 034 * case MATCH: 035 * if (policy.onChecksumMatch(...)) { 036 * return; 037 * } 038 * break; 039 * case MISMATCH: 040 * policy.onChecksumMismatch(...); 041 * break; 042 * case ERROR: 043 * policy.onChecksumError(...); 044 * break; 045 * } 046 * } 047 * policy.onNoMoreChecksums(); 048 * } 049 * 050 * void downloadFile() throws Exception { 051 * ... 052 * policy = newChecksumPolicy(); 053 * try { 054 * validateChecksums(); 055 * } catch (ChecksumFailureException e) { 056 * if (!policy.onTransferChecksumFailure(...)) { 057 * throw e; 058 * } 059 * } 060 * } 061 * </pre> 062 * <p> 063 * Checksum policies might be stateful and are generally not thread-safe. 064 */ 065public interface ChecksumPolicy 066{ 067 /** 068 * Enum denoting origin of checksum. 069 * 070 * @since 1.8.0 071 */ 072 enum ChecksumKind 073 { 074 /** 075 * Remote external kind of checksum are retrieved from remote doing extra transport round-trip (usually by 076 * getting "file.jar.sha1" for corresponding "file.jar" file). This kind of checksum is part of layout, and 077 * was from beginning the "official" (and one and only) checksum used by resolver. If no external checksum 078 * present, {@link #onNoMoreChecksums()} method is invoked that (by default) fails retrieval. 079 */ 080 REMOTE_EXTERNAL, 081 082 /** 083 * Included checksums may be received from remote repository during the retrieval of the main file, for example 084 * from response headers in case of HTTP transport. They may be set with 085 * {@link org.eclipse.aether.spi.connector.transport.GetTask#setChecksum(String, String)}. If no included 086 * checksum present, {@link #REMOTE_EXTERNAL} is tried for. 087 */ 088 REMOTE_INCLUDED, 089 090 /** 091 * Provided checksums may be provided by {@link ProvidedChecksumsSource} components, ahead of artifact 092 * retrieval. If no provided checksum present, {@link #REMOTE_INCLUDED} is tried for. 093 */ 094 PROVIDED 095 } 096 097 /** 098 * Signals a match between the locally computed checksum value and the checksum value declared by the remote 099 * repository. 100 * 101 * @param algorithm The name of the checksum algorithm being used, must not be {@code null}. 102 * @param kind A field providing further details about the checksum. 103 * @return {@code true} to accept the download as valid and stop further validation, {@code false} to continue 104 * validation with the next checksum. 105 */ 106 boolean onChecksumMatch( String algorithm, ChecksumKind kind ); 107 108 /** 109 * Signals a mismatch between the locally computed checksum value and the checksum value declared by the remote 110 * repository. A simple policy would just rethrow the provided exception. More sophisticated policies could update 111 * their internal state and defer a conclusion until all available checksums have been processed. 112 * 113 * @param algorithm The name of the checksum algorithm being used, must not be {@code null}. 114 * @param kind A field providing further details about the checksum. 115 * @param exception The exception describing the checksum mismatch, must not be {@code null}. 116 * @throws ChecksumFailureException If the checksum validation is to be failed. If the method returns normally, 117 * validation continues with the next checksum. 118 */ 119 void onChecksumMismatch( String algorithm, ChecksumKind kind, ChecksumFailureException exception ) 120 throws ChecksumFailureException; 121 122 /** 123 * Signals an error while computing the local checksum value or retrieving the checksum value from the remote 124 * repository. 125 * 126 * @param algorithm The name of the checksum algorithm being used, must not be {@code null}. 127 * @param kind A field providing further details about the checksum. 128 * @param exception The exception describing the checksum error, must not be {@code null}. 129 * @throws ChecksumFailureException If the checksum validation is to be failed. If the method returns normally, 130 * validation continues with the next checksum. 131 */ 132 void onChecksumError( String algorithm, ChecksumKind kind, ChecksumFailureException exception ) 133 throws ChecksumFailureException; 134 135 /** 136 * Signals that all available checksums have been processed. 137 * 138 * @throws ChecksumFailureException If the checksum validation is to be failed. If the method returns normally, the 139 * download is assumed to be valid. 140 */ 141 void onNoMoreChecksums() 142 throws ChecksumFailureException; 143 144 /** 145 * Signals that the download is being retried after a previously thrown {@link ChecksumFailureException} that is 146 * {@link ChecksumFailureException#isRetryWorthy() retry-worthy}. Policies that maintain internal state will usually 147 * have to reset some of this state at this point to prepare for a new round of validation. 148 */ 149 void onTransferRetry(); 150 151 /** 152 * Signals that (even after a potential retry) checksum validation has failed. A policy could opt to merely log this 153 * issue or insist on rejecting the downloaded file as unusable. 154 * 155 * @param exception The exception that was thrown from a prior call to 156 * {@link #onChecksumMismatch(String, ChecksumKind, ChecksumFailureException)}, 157 * {@link #onChecksumError(String, ChecksumKind, ChecksumFailureException)} or {@link 158 * #onNoMoreChecksums()}. 159 * @return {@code true} to accept the download nevertheless and let artifact resolution succeed, {@code false} to 160 * reject the transferred file as unusable. 161 */ 162 boolean onTransferChecksumFailure( ChecksumFailureException exception ); 163 164}