View Javadoc
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 }