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.transfer;
20  
21  import org.eclipse.aether.RepositoryException;
22  
23  /**
24   * Thrown in case of a checksum failure during an artifact/metadata download. This exception is usually thrown in
25   * following cases:
26   * <ul>
27   *     <li>actual checksum <em>mismatch</em>, see {@link #mismatch(String, String, String)}</li>
28   *     <li>lack of required checksums, see {@link #noneAvailable(String, String)}</li>
29   *     <li>processing problem during checksum checks (ie IO problem), see {@link #processingFailure(String, Throwable)}</li>
30   * </ul>
31   * It is resolver expectation to provide most available information to caller.
32   */
33  public class ChecksumFailureException extends RepositoryException {
34  
35      /** The expected checksum as declared by the hosting repository. */
36      private final String expected;
37  
38      /** The kind of the expected checksum. */
39      private final String expectedKind;
40  
41      /** The actual checksum as computed from the local bytes. */
42      private final String actual;
43  
44      /** Whether retrying the download might solve the checksum failure. */
45      private final boolean retryWorthy;
46  
47      /**
48       * Use in case of checksum mismatch. Creates a new exception with the specified expected, expected kind and actual
49       * checksum. The resulting exception is {@link #isRetryWorthy() retry-worthy}. The checksum match check should
50       * have already happened, this method does not check for any kind of inequality.
51       *
52       * @param expected The expected checksum as declared by the hosting repository, may be {@code null}.
53       * @param expectedKind The expected checksum kind, may be {@code null}.
54       * @param actual The actual checksum as computed from the local bytes, may be {@code null}.
55       * @return The new exception, never {@code null}.
56       * @since 2.0.19
57       */
58      public static ChecksumFailureException mismatch(String expected, String expectedKind, String actual) {
59          return mismatchDetail(null, expected, expectedKind, actual);
60      }
61  
62      /**
63       * Use in case of checksum mismatch. Creates a new exception with the specified expected, expected kind and actual
64       * checksum. The resulting exception is {@link #isRetryWorthy() retry-worthy}. The checksum match check should
65       * have already happened, this method does not check for any kind of inequality.
66       *
67       * @param detail The extra detail/information regarding mismatch.
68       * @param expected The expected checksum as declared by the hosting repository, may be {@code null}.
69       * @param expectedKind The expected checksum kind, may be {@code null}.
70       * @param actual The actual checksum as computed from the local bytes, may be {@code null}.
71       * @return The new exception, never {@code null}.
72       * @since 2.0.19
73       */
74      public static ChecksumFailureException mismatchDetail(
75              String detail, String expected, String expectedKind, String actual) {
76          String message = "Checksum validation failed, expected '"
77                  + sanitize(expected) + "'" + (expectedKind == null ? "" : " (" + sanitize(expectedKind) + ")")
78                  + " but is actually '" + sanitize(actual) + "'";
79          if (detail != null) {
80              message = message + " (" + sanitize(detail) + ")";
81          }
82          return new ChecksumFailureException(message, null, expected, expectedKind, actual, true);
83      }
84  
85      /**
86       * Replaces ISO control characters below U+0020 (except LF and TAB) and DEL (U+007F) with their visible
87       * {@code \}{@code uXXXX} escapes. The expected checksum value is remote-supplied and ends up in log output (the
88       * default "warn" checksum policy logs this exception's message as the sole integrity warning): raw terminal
89       * control characters such as ESC or CR embedded in it could erase or forge that log line. The
90       * {@link #getExpected()}, {@link #getExpectedKind()} and {@link #getActual()} accessors keep returning the
91       * raw values.
92       */
93      private static String sanitize(String value) {
94          if (value == null) {
95              return null;
96          }
97          StringBuilder result = null;
98          for (int i = 0; i < value.length(); i++) {
99              char c = value.charAt(i);
100             if ((c < 0x20 && c != '\n' && c != '\t') || c == 0x7f) {
101                 if (result == null) {
102                     result = new StringBuilder(value.length() + 16);
103                     result.append(value, 0, i);
104                 }
105                 result.append(String.format("\\u%04X", (int) c));
106             } else if (result != null) {
107                 result.append(c);
108             }
109         }
110         return result == null ? value : result.toString();
111     }
112 
113     /**
114      * Use in case of checksum not available. Optionally, one can specify which kind was not available.
115      *
116      * @param message The message.
117      * @param expectedKind The expected checksum kind, may be {@code null}.
118      * @return The new exception, never {@code null}.
119      * @since 2.0.19
120      */
121     public static ChecksumFailureException noneAvailable(String message, String expectedKind) {
122         return new ChecksumFailureException(message, null, "", expectedKind == null ? "" : expectedKind, "", false);
123     }
124 
125     /**
126      * Use in case of error, for example IO problem during checksum processing, calculation and alike. Ideally, one
127      * should specify cause as well.
128      *
129      * @param message The message.
130      * @param cause The cause.
131      * @return The new exception, never {@code null}.
132      * @since 2.0.19
133      */
134     public static ChecksumFailureException processingFailure(String message, Throwable cause) {
135         return new ChecksumFailureException(message, cause, "", "", "", false);
136     }
137 
138     /**
139      * Creates a new exception with the specified expected, expected kind and actual checksum. The resulting exception
140      * is {@link #isRetryWorthy() retry-worthy}.
141      *
142      * @param expected The expected checksum as declared by the hosting repository, may be {@code null}.
143      * @param expectedKind The expected checksum kind, may be {@code null}.
144      * @param actual The actual checksum as computed from the local bytes, may be {@code null}.
145      * @since 1.8.0
146      * @deprecated Use {@link #mismatch(String, String, String)} or other suitable helper method instead.
147      */
148     @Deprecated
149     public ChecksumFailureException(String expected, String expectedKind, String actual) {
150         super("Checksum validation failed, expected '"
151                 + sanitize(expected) + "'" + (expectedKind == null ? "" : " (" + sanitize(expectedKind) + ")")
152                 + " but is actually '" + sanitize(actual) + "'");
153         this.expected = expected;
154         this.expectedKind = expectedKind;
155         this.actual = actual;
156         this.retryWorthy = true;
157     }
158 
159     /**
160      * Creates a new exception with the specified detail message. The resulting exception is not
161      * {@link #isRetryWorthy() retry-worthy}. Use this constructor ONLY in cases like "no data to work with",
162      * like missing checksums. In every other case use some other constructor.
163      *
164      * @param message The detail message, may be {@code null}.
165      * @deprecated Use {@link #noneAvailable(String, String)} or other suitable helper method instead.
166      */
167     @Deprecated
168     public ChecksumFailureException(String message) {
169         this(message, null, "", "", "", false);
170     }
171 
172     /**
173      * Creates a new exception with the specified cause. The resulting exception is not {@link #isRetryWorthy()
174      * retry-worthy}. Use this constructor in case some other error (ie IO problem) prevented checksum calculation.
175      *
176      * @param cause The exception that caused this one, may be {@code null}.
177      * @deprecated Use {@link #processingFailure(String, Throwable)} or other helper method instead.
178      */
179     @Deprecated
180     public ChecksumFailureException(Throwable cause) {
181         this("Checksum validation failed" + getMessage(": ", cause), cause, "", "", "", false);
182     }
183 
184     /**
185      * Creates a new exception with the specified detail message and cause. The resulting exception is not
186      * {@link #isRetryWorthy() retry-worthy}. Use this constructor in case some other error (ie IO problem)
187      * prevented checksum calculation.
188      *
189      * @param message The detail message, may be {@code null}.
190      * @param cause The exception that caused this one, may be {@code null}.
191      * @deprecated Use {@link #processingFailure(String, Throwable)} or other helper method instead.
192      */
193     @Deprecated
194     public ChecksumFailureException(String message, Throwable cause) {
195         this(message, cause, "", "", "", false);
196     }
197 
198     /**
199      * Creates a new exception with the specified retry flag, detail message and cause.
200      *
201      * @param retryWorthy {@code true} if the exception is retry-worthy, {@code false} otherwise.
202      * @param message The detail message, may be {@code null}.
203      * @param cause The exception that caused this one, may be {@code null}.
204      * @deprecated Do not use this constructor, it lacks information.
205      */
206     @Deprecated
207     public ChecksumFailureException(boolean retryWorthy, String message, Throwable cause) {
208         this(message, cause, "", "", "", retryWorthy);
209     }
210 
211     /**
212      * Hidden constructor, use static helper methods instead, suitable for your case.
213      */
214     private ChecksumFailureException(
215             String message, Throwable cause, String expected, String expectedKind, String actual, boolean retryWorthy) {
216         super(message, cause);
217         this.expected = expected;
218         this.expectedKind = expectedKind;
219         this.actual = actual;
220         this.retryWorthy = retryWorthy;
221     }
222 
223     /**
224      * Gets the expected checksum for the downloaded artifact/metadata.
225      *
226      * @return The expected checksum as declared by the hosting repository or {@code null} if unknown.
227      */
228     public String getExpected() {
229         return expected;
230     }
231 
232     /**
233      * Gets the expected checksum kind for the downloaded artifact/metadata.
234      *
235      * @return The expected checksum kind or {@code null} if unknown.
236      * @since 1.8.0
237      */
238     public String getExpectedKind() {
239         return expectedKind;
240     }
241 
242     /**
243      * Gets the actual checksum for the downloaded artifact/metadata.
244      *
245      * @return The actual checksum as computed from the local bytes or {@code null} if unknown.
246      */
247     public String getActual() {
248         return actual;
249     }
250 
251     /**
252      * Indicates whether the corresponding download is retry-worthy.
253      *
254      * @return {@code true} if retrying the download might solve the checksum failure, {@code false} if the checksum
255      *         failure is non-recoverable.
256      */
257     public boolean isRetryWorthy() {
258         return retryWorthy;
259     }
260 }