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