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