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 org.eclipse.aether.spi.checksums.ProvidedChecksumsSource}
89 * components, ahead of artifact retrieval. If no provided checksum present, {@link #REMOTE_INCLUDED} is
90 * tried for.
91 */
92 PROVIDED
93 }
94
95 /**
96 * Signals a match between the locally computed checksum value and the checksum value declared by the remote
97 * repository.
98 *
99 * @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 }