1 /*
2 * Copyright (C) 2013 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5 * in compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License
10 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11 * or implied. See the License for the specific language governing permissions and limitations under
12 * the License.
13 */
14
15 package com.google.common.base;
16
17 import static com.google.common.base.Strings.lenientFormat;
18
19 import com.google.common.annotations.GwtCompatible;
20 import com.google.errorprone.annotations.CanIgnoreReturnValue;
21 import javax.annotation.CheckForNull;
22 import org.checkerframework.checker.nullness.qual.Nullable;
23
24 /**
25 * Static convenience methods that serve the same purpose as Java language <a
26 * href="https://docs.oracle.com/javase/8/docs/technotes/guides/language/assert.html">assertions</a>,
27 * except that they are always enabled. These methods should be used instead of Java assertions
28 * whenever there is a chance the check may fail "in real life". Example:
29 *
30 * <pre>{@code
31 * Bill bill = remoteService.getLastUnpaidBill();
32 *
33 * // In case bug 12345 happens again we'd rather just die
34 * Verify.verify(bill.status() == Status.UNPAID,
35 * "Unexpected bill status: %s", bill.status());
36 * }</pre>
37 *
38 * <h3>Comparison to alternatives</h3>
39 *
40 * <p><b>Note:</b> In some cases the differences explained below can be subtle. When it's unclear
41 * which approach to use, <b>don't worry</b> too much about it; just pick something that seems
42 * reasonable and it will be fine.
43 *
44 * <ul>
45 * <li>If checking whether the <i>caller</i> has violated your method or constructor's contract
46 * (such as by passing an invalid argument), use the utilities of the {@link Preconditions}
47 * class instead.
48 * <li>If checking an <i>impossible</i> condition (which <i>cannot</i> happen unless your own
49 * class or its <i>trusted</i> dependencies is badly broken), this is what ordinary Java
50 * assertions are for. Note that assertions are not enabled by default; they are essentially
51 * considered "compiled comments."
52 * <li>An explicit {@code if/throw} (as illustrated below) is always acceptable; we still
53 * recommend using our {@link VerifyException} exception type. Throwing a plain {@link
54 * RuntimeException} is frowned upon.
55 * <li>Use of {@link java.util.Objects#requireNonNull(Object)} is generally discouraged, since
56 * {@link #verifyNotNull(Object)} and {@link Preconditions#checkNotNull(Object)} perform the
57 * same function with more clarity.
58 * </ul>
59 *
60 * <h3>Warning about performance</h3>
61 *
62 * <p>Remember that parameter values for message construction must all be computed eagerly, and
63 * autoboxing and varargs array creation may happen as well, even when the verification succeeds and
64 * the message ends up unneeded. Performance-sensitive verification checks should continue to use
65 * usual form:
66 *
67 * <pre>{@code
68 * Bill bill = remoteService.getLastUnpaidBill();
69 * if (bill.status() != Status.UNPAID) {
70 * throw new VerifyException("Unexpected bill status: " + bill.status());
71 * }
72 * }</pre>
73 *
74 * <h3>Only {@code %s} is supported</h3>
75 *
76 * <p>As with {@link Preconditions}, {@code Verify} uses {@link Strings#lenientFormat} to format
77 * error message template strings. This only supports the {@code "%s"} specifier, not the full range
78 * of {@link java.util.Formatter} specifiers. However, note that if the number of arguments does not
79 * match the number of occurrences of {@code "%s"} in the format string, {@code Verify} will still
80 * behave as expected, and will still include all argument values in the error message; the message
81 * will simply not be formatted exactly as intended.
82 *
83 * <h3>More information</h3>
84 *
85 * See <a href="https://github.com/google/guava/wiki/ConditionalFailuresExplained">Conditional
86 * failures explained</a> in the Guava User Guide for advice on when this class should be used.
87 *
88 * @since 17.0
89 */
90 @GwtCompatible
91 @ElementTypesAreNonnullByDefault
92 public final class Verify {
93 /**
94 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with no
95 * message otherwise.
96 *
97 * @throws VerifyException if {@code expression} is {@code false}
98 * @see Preconditions#checkState Preconditions.checkState()
99 */
100 public static void verify(boolean expression) {
101 if (!expression) {
102 throw new VerifyException();
103 }
104 }
105
106 /**
107 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
108 * custom message otherwise.
109 *
110 * @param expression a boolean expression
111 * @param errorMessageTemplate a template for the exception message should the check fail. The
112 * message is formed by replacing each {@code %s} placeholder in the template with an
113 * argument. These are matched by position - the first {@code %s} gets {@code
114 * errorMessageArgs[0]}, etc. Unmatched arguments will be appended to the formatted message in
115 * square braces. Unmatched placeholders will be left as-is.
116 * @param errorMessageArgs the arguments to be substituted into the message template. Arguments
117 * are converted to strings using {@link String#valueOf(Object)}.
118 * @throws VerifyException if {@code expression} is {@code false}
119 * @see Preconditions#checkState Preconditions.checkState()
120 */
121 public static void verify(
122 boolean expression,
123 String errorMessageTemplate,
124 @CheckForNull @Nullable Object... errorMessageArgs) {
125 if (!expression) {
126 throw new VerifyException(lenientFormat(errorMessageTemplate, errorMessageArgs));
127 }
128 }
129
130 /**
131 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
132 * custom message otherwise.
133 *
134 * <p>See {@link #verify(boolean, String, Object...)} for details.
135 *
136 * @since 23.1 (varargs overload since 17.0)
137 */
138 public static void verify(boolean expression, String errorMessageTemplate, char p1) {
139 if (!expression) {
140 throw new VerifyException(lenientFormat(errorMessageTemplate, p1));
141 }
142 }
143
144 /**
145 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
146 * custom message otherwise.
147 *
148 * <p>See {@link #verify(boolean, String, Object...)} for details.
149 *
150 * @since 23.1 (varargs overload since 17.0)
151 */
152 public static void verify(boolean expression, String errorMessageTemplate, int p1) {
153 if (!expression) {
154 throw new VerifyException(lenientFormat(errorMessageTemplate, p1));
155 }
156 }
157
158 /**
159 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
160 * custom message otherwise.
161 *
162 * <p>See {@link #verify(boolean, String, Object...)} for details.
163 *
164 * @since 23.1 (varargs overload since 17.0)
165 */
166 public static void verify(boolean expression, String errorMessageTemplate, long p1) {
167 if (!expression) {
168 throw new VerifyException(lenientFormat(errorMessageTemplate, p1));
169 }
170 }
171
172 /**
173 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
174 * custom message otherwise.
175 *
176 * <p>See {@link #verify(boolean, String, Object...)} for details.
177 *
178 * @since 23.1 (varargs overload since 17.0)
179 */
180 public static void verify(
181 boolean expression, String errorMessageTemplate, @CheckForNull Object p1) {
182 if (!expression) {
183 throw new VerifyException(lenientFormat(errorMessageTemplate, p1));
184 }
185 }
186
187 /**
188 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
189 * custom message otherwise.
190 *
191 * <p>See {@link #verify(boolean, String, Object...)} for details.
192 *
193 * @since 23.1 (varargs overload since 17.0)
194 */
195 public static void verify(boolean expression, String errorMessageTemplate, char p1, char p2) {
196 if (!expression) {
197 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
198 }
199 }
200
201 /**
202 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
203 * custom message otherwise.
204 *
205 * <p>See {@link #verify(boolean, String, Object...)} for details.
206 *
207 * @since 23.1 (varargs overload since 17.0)
208 */
209 public static void verify(boolean expression, String errorMessageTemplate, int p1, char p2) {
210 if (!expression) {
211 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
212 }
213 }
214
215 /**
216 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
217 * custom message otherwise.
218 *
219 * <p>See {@link #verify(boolean, String, Object...)} for details.
220 *
221 * @since 23.1 (varargs overload since 17.0)
222 */
223 public static void verify(boolean expression, String errorMessageTemplate, long p1, char p2) {
224 if (!expression) {
225 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
226 }
227 }
228
229 /**
230 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
231 * custom message otherwise.
232 *
233 * <p>See {@link #verify(boolean, String, Object...)} for details.
234 *
235 * @since 23.1 (varargs overload since 17.0)
236 */
237 public static void verify(
238 boolean expression, String errorMessageTemplate, @CheckForNull Object p1, char p2) {
239 if (!expression) {
240 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
241 }
242 }
243
244 /**
245 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
246 * custom message otherwise.
247 *
248 * <p>See {@link #verify(boolean, String, Object...)} for details.
249 *
250 * @since 23.1 (varargs overload since 17.0)
251 */
252 public static void verify(boolean expression, String errorMessageTemplate, char p1, int p2) {
253 if (!expression) {
254 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
255 }
256 }
257
258 /**
259 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
260 * custom message otherwise.
261 *
262 * <p>See {@link #verify(boolean, String, Object...)} for details.
263 *
264 * @since 23.1 (varargs overload since 17.0)
265 */
266 public static void verify(boolean expression, String errorMessageTemplate, int p1, int p2) {
267 if (!expression) {
268 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
269 }
270 }
271
272 /**
273 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
274 * custom message otherwise.
275 *
276 * <p>See {@link #verify(boolean, String, Object...)} for details.
277 *
278 * @since 23.1 (varargs overload since 17.0)
279 */
280 public static void verify(boolean expression, String errorMessageTemplate, long p1, int p2) {
281 if (!expression) {
282 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
283 }
284 }
285
286 /**
287 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
288 * custom message otherwise.
289 *
290 * <p>See {@link #verify(boolean, String, Object...)} for details.
291 *
292 * @since 23.1 (varargs overload since 17.0)
293 */
294 public static void verify(
295 boolean expression, String errorMessageTemplate, @CheckForNull Object p1, int p2) {
296 if (!expression) {
297 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
298 }
299 }
300
301 /**
302 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
303 * custom message otherwise.
304 *
305 * <p>See {@link #verify(boolean, String, Object...)} for details.
306 *
307 * @since 23.1 (varargs overload since 17.0)
308 */
309 public static void verify(boolean expression, String errorMessageTemplate, char p1, long p2) {
310 if (!expression) {
311 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
312 }
313 }
314
315 /**
316 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
317 * custom message otherwise.
318 *
319 * <p>See {@link #verify(boolean, String, Object...)} for details.
320 *
321 * @since 23.1 (varargs overload since 17.0)
322 */
323 public static void verify(boolean expression, String errorMessageTemplate, int p1, long p2) {
324 if (!expression) {
325 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
326 }
327 }
328
329 /**
330 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
331 * custom message otherwise.
332 *
333 * <p>See {@link #verify(boolean, String, Object...)} for details.
334 *
335 * @since 23.1 (varargs overload since 17.0)
336 */
337 public static void verify(boolean expression, String errorMessageTemplate, long p1, long p2) {
338 if (!expression) {
339 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
340 }
341 }
342
343 /**
344 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
345 * custom message otherwise.
346 *
347 * <p>See {@link #verify(boolean, String, Object...)} for details.
348 *
349 * @since 23.1 (varargs overload since 17.0)
350 */
351 public static void verify(
352 boolean expression, String errorMessageTemplate, @CheckForNull Object p1, long p2) {
353 if (!expression) {
354 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
355 }
356 }
357
358 /**
359 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
360 * custom message otherwise.
361 *
362 * <p>See {@link #verify(boolean, String, Object...)} for details.
363 *
364 * @since 23.1 (varargs overload since 17.0)
365 */
366 public static void verify(
367 boolean expression, String errorMessageTemplate, char p1, @CheckForNull Object p2) {
368 if (!expression) {
369 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
370 }
371 }
372
373 /**
374 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
375 * custom message otherwise.
376 *
377 * <p>See {@link #verify(boolean, String, Object...)} for details.
378 *
379 * @since 23.1 (varargs overload since 17.0)
380 */
381 public static void verify(
382 boolean expression, String errorMessageTemplate, int p1, @CheckForNull Object p2) {
383 if (!expression) {
384 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
385 }
386 }
387
388 /**
389 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
390 * custom message otherwise.
391 *
392 * <p>See {@link #verify(boolean, String, Object...)} for details.
393 *
394 * @since 23.1 (varargs overload since 17.0)
395 */
396 public static void verify(
397 boolean expression, String errorMessageTemplate, long p1, @CheckForNull Object p2) {
398 if (!expression) {
399 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
400 }
401 }
402
403 /**
404 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
405 * custom message otherwise.
406 *
407 * <p>See {@link #verify(boolean, String, Object...)} for details.
408 *
409 * @since 23.1 (varargs overload since 17.0)
410 */
411 public static void verify(
412 boolean expression,
413 String errorMessageTemplate,
414 @CheckForNull Object p1,
415 @CheckForNull Object p2) {
416 if (!expression) {
417 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
418 }
419 }
420
421 /**
422 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
423 * custom message otherwise.
424 *
425 * <p>See {@link #verify(boolean, String, Object...)} for details.
426 *
427 * @since 23.1 (varargs overload since 17.0)
428 */
429 public static void verify(
430 boolean expression,
431 String errorMessageTemplate,
432 @CheckForNull Object p1,
433 @CheckForNull Object p2,
434 @CheckForNull Object p3) {
435 if (!expression) {
436 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2, p3));
437 }
438 }
439
440 /**
441 * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
442 * custom message otherwise.
443 *
444 * <p>See {@link #verify(boolean, String, Object...)} for details.
445 *
446 * @since 23.1 (varargs overload since 17.0)
447 */
448 public static void verify(
449 boolean expression,
450 String errorMessageTemplate,
451 @CheckForNull Object p1,
452 @CheckForNull Object p2,
453 @CheckForNull Object p3,
454 @CheckForNull Object p4) {
455 if (!expression) {
456 throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2, p3, p4));
457 }
458 }
459
460 /*
461 * For a discussion of the signature of verifyNotNull, see the discussion above
462 * Preconditions.checkNotNull.
463 *
464 * (verifyNotNull has many fewer "problem" callers, so we could try to be stricter. On the other
465 * hand, verifyNotNull arguably has more reason to accept nullable arguments in the first
466 * place....)
467 */
468
469 /**
470 * Ensures that {@code reference} is non-null, throwing a {@code VerifyException} with a default
471 * message otherwise.
472 *
473 * @return {@code reference}, guaranteed to be non-null, for convenience
474 * @throws VerifyException if {@code reference} is {@code null}
475 * @see Preconditions#checkNotNull Preconditions.checkNotNull()
476 */
477 @CanIgnoreReturnValue
478 public static <T> T verifyNotNull(@CheckForNull T reference) {
479 return verifyNotNull(reference, "expected a non-null reference");
480 }
481
482 /**
483 * Ensures that {@code reference} is non-null, throwing a {@code VerifyException} with a custom
484 * message otherwise.
485 *
486 * @param errorMessageTemplate a template for the exception message should the check fail. The
487 * message is formed by replacing each {@code %s} placeholder in the template with an
488 * argument. These are matched by position - the first {@code %s} gets {@code
489 * errorMessageArgs[0]}, etc. Unmatched arguments will be appended to the formatted message in
490 * square braces. Unmatched placeholders will be left as-is.
491 * @param errorMessageArgs the arguments to be substituted into the message template. Arguments
492 * are converted to strings using {@link String#valueOf(Object)}.
493 * @return {@code reference}, guaranteed to be non-null, for convenience
494 * @throws VerifyException if {@code reference} is {@code null}
495 * @see Preconditions#checkNotNull Preconditions.checkNotNull()
496 */
497 @CanIgnoreReturnValue
498 public static <T> T verifyNotNull(
499 @CheckForNull T reference,
500 String errorMessageTemplate,
501 @CheckForNull @Nullable Object... errorMessageArgs) {
502 if (reference == null) {
503 throw new VerifyException(lenientFormat(errorMessageTemplate, errorMessageArgs));
504 }
505 return reference;
506 }
507
508 // TODO(kevinb): consider <T> T verifySingleton(Iterable<T>) to take over for
509 // Iterables.getOnlyElement()
510
511 private Verify() {}
512 }