1 package org.eclipse.aether.spi.connector.checksum;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import org.eclipse.aether.transfer.ChecksumFailureException;
23
24 /**
25 * A checksum policy gets employed by repository connectors to validate the integrity of a downloaded file. For each
26 * downloaded file, a checksum policy instance is obtained and presented with the available checksums to conclude
27 * whether the download is valid or not. The following pseudo-code illustrates the usage of a checksum policy by a
28 * repository connector in some more detail (the retry logic has been omitted for the sake of brevity):
29 *
30 * <pre>
31 * void validateChecksums() throws ChecksumFailureException {
32 * for (checksum : checksums) {
33 * switch (checksum.state) {
34 * case MATCH:
35 * if (policy.onChecksumMatch(...)) {
36 * return;
37 * }
38 * break;
39 * case MISMATCH:
40 * policy.onChecksumMismatch(...);
41 * break;
42 * case ERROR:
43 * policy.onChecksumError(...);
44 * break;
45 * }
46 * }
47 * policy.onNoMoreChecksums();
48 * }
49 *
50 * void downloadFile() throws Exception {
51 * ...
52 * policy = newChecksumPolicy();
53 * try {
54 * validateChecksums();
55 * } catch (ChecksumFailureException e) {
56 * if (!policy.onTransferChecksumFailure(...)) {
57 * throw e;
58 * }
59 * }
60 * }
61 * </pre>
62 * <p>
63 * Checksum policies might be stateful and are generally not thread-safe.
64 */
65 public interface ChecksumPolicy
66 {
67 /**
68 * Enum denoting origin of checksum.
69 *
70 * @since 1.8.0
71 */
72 enum ChecksumKind
73 {
74 /**
75 * Remote external kind of checksum are retrieved from remote doing extra transport round-trip (usually by
76 * getting "file.jar.sha1" for corresponding "file.jar" file). This kind of checksum is part of layout, and
77 * was from beginning the "official" (and one and only) checksum used by resolver. If no external checksum
78 * present, {@link #onNoMoreChecksums()} method is invoked that (by default) fails retrieval.
79 */
80 REMOTE_EXTERNAL,
81
82 /**
83 * Included checksums may be received from remote repository during the retrieval of the main file, for example
84 * from response headers in case of HTTP transport. They may be set with
85 * {@link org.eclipse.aether.spi.connector.transport.GetTask#setChecksum(String, String)}. If no included
86 * checksum present, {@link #REMOTE_EXTERNAL} is tried for.
87 */
88 REMOTE_INCLUDED,
89
90 /**
91 * Provided checksums may be provided by {@link ProvidedChecksumsSource} components, ahead of artifact
92 * retrieval. If no provided checksum present, {@link #REMOTE_INCLUDED} is tried for.
93 */
94 PROVIDED
95 }
96
97 /**
98 * Signals a match between the locally computed checksum value and the checksum value declared by the remote
99 * 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 }