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}