Source code

001/*
002 * Copyright (C) 2013 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.base;
016
017import static com.google.common.base.Preconditions.format;
018
019import com.google.common.annotations.GwtCompatible;
020import com.google.errorprone.annotations.CanIgnoreReturnValue;
021import org.checkerframework.checker.nullness.compatqual.NullableDecl;
022
023/**
024 * Static convenience methods that serve the same purpose as Java language <a
025 * href="http://docs.oracle.com/javase/7/docs/technotes/guides/language/assert.html">assertions</a>,
026 * except that they are always enabled. These methods should be used instead of Java assertions
027 * whenever there is a chance the check may fail "in real life". Example:
028 *
029 * <pre>{@code
030 * Bill bill = remoteService.getLastUnpaidBill();
031 *
032 * // In case bug 12345 happens again we'd rather just die
033 * Verify.verify(bill.status() == Status.UNPAID,
034 *     "Unexpected bill status: %s", bill.status());
035 * }</pre>
036 *
037 * <h3>Comparison to alternatives</h3>
038 *
039 * <p><b>Note:</b> In some cases the differences explained below can be subtle. When it's unclear
040 * which approach to use, <b>don't worry</b> too much about it; just pick something that seems
041 * reasonable and it will be fine.
042 *
043 * <ul>
044 *   <li>If checking whether the <i>caller</i> has violated your method or constructor's contract
045 *       (such as by passing an invalid argument), use the utilities of the {@link Preconditions}
046 *       class instead.
047 *   <li>If checking an <i>impossible</i> condition (which <i>cannot</i> happen unless your own
048 *       class or its <i>trusted</i> dependencies is badly broken), this is what ordinary Java
049 *       assertions are for. Note that assertions are not enabled by default; they are essentially
050 *       considered "compiled comments."
051 *   <li>An explicit {@code if/throw} (as illustrated below) is always acceptable; we still
052 *       recommend using our {@link VerifyException} exception type. Throwing a plain {@link
053 *       RuntimeException} is frowned upon.
054 *   <li>Use of {@link java.util.Objects#requireNonNull(Object)} is generally discouraged, since
055 *       {@link #verifyNotNull(Object)} and {@link Preconditions#checkNotNull(Object)} perform the
056 *       same function with more clarity.
057 * </ul>
058 *
059 * <h3>Warning about performance</h3>
060 *
061 * <p>Remember that parameter values for message construction must all be computed eagerly, and
062 * autoboxing and varargs array creation may happen as well, even when the verification succeeds and
063 * the message ends up unneeded. Performance-sensitive verification checks should continue to use
064 * usual form:
065 *
066 * <pre>{@code
067 * Bill bill = remoteService.getLastUnpaidBill();
068 * if (bill.status() != Status.UNPAID) {
069 *   throw new VerifyException("Unexpected bill status: " + bill.status());
070 * }
071 * }</pre>
072 *
073 * <h3>Only {@code %s} is supported</h3>
074 *
075 * <p>As with {@link Preconditions} error message template strings, only the {@code "%s"} specifier
076 * is supported, not the full range of {@link java.util.Formatter} specifiers. However, note that if
077 * the number of arguments does not match the number of occurrences of {@code "%s"} in the format
078 * string, {@code Verify} will still behave as expected, and will still include all argument values
079 * in the error message; the message will simply not be formatted exactly as intended.
080 *
081 * <h3>More information</h3>
082 *
083 * See <a href="https://github.com/google/guava/wiki/ConditionalFailuresExplained">Conditional
084 * failures explained</a> in the Guava User Guide for advice on when this class should be used.
085 *
086 * @since 17.0
087 */
088@GwtCompatible
089public final class Verify {
090  /**
091   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with no
092   * message otherwise.
093   *
094   * @throws VerifyException if {@code expression} is {@code false}
095   * @see Preconditions#checkState Preconditions.checkState()
096   */
097  public static void verify(boolean expression) {
098    if (!expression) {
099      throw new VerifyException();
100    }
101  }
102
103  /**
104   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
105   * custom message otherwise.
106   *
107   * @param expression a boolean expression
108   * @param errorMessageTemplate a template for the exception message should the check fail. The
109   *     message is formed by replacing each {@code %s} placeholder in the template with an
110   *     argument. These are matched by position - the first {@code %s} gets {@code
111   *     errorMessageArgs[0]}, etc. Unmatched arguments will be appended to the formatted message in
112   *     square braces. Unmatched placeholders will be left as-is.
113   * @param errorMessageArgs the arguments to be substituted into the message template. Arguments
114   *     are converted to strings using {@link String#valueOf(Object)}.
115   * @throws VerifyException if {@code expression} is {@code false}
116   * @see Preconditions#checkState Preconditions.checkState()
117   */
118  public static void verify(
119      boolean expression,
120      @NullableDecl String errorMessageTemplate,
121      @NullableDecl Object... errorMessageArgs) {
122    if (!expression) {
123      throw new VerifyException(format(errorMessageTemplate, errorMessageArgs));
124    }
125  }
126
127  /**
128   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
129   * custom message otherwise.
130   *
131   * <p>See {@link #verify(boolean, String, Object...)} for details.
132   *
133   * @since 23.1 (varargs overload since 17.0)
134   */
135  public static void verify(
136      boolean expression, @NullableDecl 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, @NullableDecl 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(
165      boolean expression, @NullableDecl String errorMessageTemplate, long p1) {
166    if (!expression) {
167      throw new VerifyException(format(errorMessageTemplate, p1));
168    }
169  }
170
171  /**
172   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
173   * custom message otherwise.
174   *
175   * <p>See {@link #verify(boolean, String, Object...)} for details.
176   *
177   * @since 23.1 (varargs overload since 17.0)
178   */
179  public static void verify(
180      boolean expression, @NullableDecl String errorMessageTemplate, @NullableDecl Object p1) {
181    if (!expression) {
182      throw new VerifyException(format(errorMessageTemplate, p1));
183    }
184  }
185
186  /**
187   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
188   * custom message otherwise.
189   *
190   * <p>See {@link #verify(boolean, String, Object...)} for details.
191   *
192   * @since 23.1 (varargs overload since 17.0)
193   */
194  public static void verify(
195      boolean expression, @NullableDecl String errorMessageTemplate, char p1, char p2) {
196    if (!expression) {
197      throw new VerifyException(format(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(
210      boolean expression, @NullableDecl String errorMessageTemplate, int p1, char p2) {
211    if (!expression) {
212      throw new VerifyException(format(errorMessageTemplate, p1, p2));
213    }
214  }
215
216  /**
217   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
218   * custom message otherwise.
219   *
220   * <p>See {@link #verify(boolean, String, Object...)} for details.
221   *
222   * @since 23.1 (varargs overload since 17.0)
223   */
224  public static void verify(
225      boolean expression, @NullableDecl String errorMessageTemplate, long p1, char p2) {
226    if (!expression) {
227      throw new VerifyException(format(errorMessageTemplate, p1, p2));
228    }
229  }
230
231  /**
232   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
233   * custom message otherwise.
234   *
235   * <p>See {@link #verify(boolean, String, Object...)} for details.
236   *
237   * @since 23.1 (varargs overload since 17.0)
238   */
239  public static void verify(
240      boolean expression,
241      @NullableDecl String errorMessageTemplate,
242      @NullableDecl Object p1,
243      char p2) {
244    if (!expression) {
245      throw new VerifyException(format(errorMessageTemplate, p1, p2));
246    }
247  }
248
249  /**
250   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
251   * custom message otherwise.
252   *
253   * <p>See {@link #verify(boolean, String, Object...)} for details.
254   *
255   * @since 23.1 (varargs overload since 17.0)
256   */
257  public static void verify(
258      boolean expression, @NullableDecl String errorMessageTemplate, char p1, int p2) {
259    if (!expression) {
260      throw new VerifyException(format(errorMessageTemplate, p1, p2));
261    }
262  }
263
264  /**
265   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
266   * custom message otherwise.
267   *
268   * <p>See {@link #verify(boolean, String, Object...)} for details.
269   *
270   * @since 23.1 (varargs overload since 17.0)
271   */
272  public static void verify(
273      boolean expression, @NullableDecl String errorMessageTemplate, int p1, int p2) {
274    if (!expression) {
275      throw new VerifyException(format(errorMessageTemplate, p1, p2));
276    }
277  }
278
279  /**
280   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
281   * custom message otherwise.
282   *
283   * <p>See {@link #verify(boolean, String, Object...)} for details.
284   *
285   * @since 23.1 (varargs overload since 17.0)
286   */
287  public static void verify(
288      boolean expression, @NullableDecl String errorMessageTemplate, long p1, int p2) {
289    if (!expression) {
290      throw new VerifyException(format(errorMessageTemplate, p1, p2));
291    }
292  }
293
294  /**
295   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
296   * custom message otherwise.
297   *
298   * <p>See {@link #verify(boolean, String, Object...)} for details.
299   *
300   * @since 23.1 (varargs overload since 17.0)
301   */
302  public static void verify(
303      boolean expression,
304      @NullableDecl String errorMessageTemplate,
305      @NullableDecl Object p1,
306      int p2) {
307    if (!expression) {
308      throw new VerifyException(format(errorMessageTemplate, p1, p2));
309    }
310  }
311
312  /**
313   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
314   * custom message otherwise.
315   *
316   * <p>See {@link #verify(boolean, String, Object...)} for details.
317   *
318   * @since 23.1 (varargs overload since 17.0)
319   */
320  public static void verify(
321      boolean expression, @NullableDecl String errorMessageTemplate, char p1, long p2) {
322    if (!expression) {
323      throw new VerifyException(format(errorMessageTemplate, p1, p2));
324    }
325  }
326
327  /**
328   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
329   * custom message otherwise.
330   *
331   * <p>See {@link #verify(boolean, String, Object...)} for details.
332   *
333   * @since 23.1 (varargs overload since 17.0)
334   */
335  public static void verify(
336      boolean expression, @NullableDecl String errorMessageTemplate, int p1, long p2) {
337    if (!expression) {
338      throw new VerifyException(format(errorMessageTemplate, p1, p2));
339    }
340  }
341
342  /**
343   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
344   * custom message otherwise.
345   *
346   * <p>See {@link #verify(boolean, String, Object...)} for details.
347   *
348   * @since 23.1 (varargs overload since 17.0)
349   */
350  public static void verify(
351      boolean expression, @NullableDecl String errorMessageTemplate, long p1, long p2) {
352    if (!expression) {
353      throw new VerifyException(format(errorMessageTemplate, p1, p2));
354    }
355  }
356
357  /**
358   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
359   * custom message otherwise.
360   *
361   * <p>See {@link #verify(boolean, String, Object...)} for details.
362   *
363   * @since 23.1 (varargs overload since 17.0)
364   */
365  public static void verify(
366      boolean expression,
367      @NullableDecl String errorMessageTemplate,
368      @NullableDecl Object p1,
369      long p2) {
370    if (!expression) {
371      throw new VerifyException(format(errorMessageTemplate, p1, p2));
372    }
373  }
374
375  /**
376   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
377   * custom message otherwise.
378   *
379   * <p>See {@link #verify(boolean, String, Object...)} for details.
380   *
381   * @since 23.1 (varargs overload since 17.0)
382   */
383  public static void verify(
384      boolean expression,
385      @NullableDecl String errorMessageTemplate,
386      char p1,
387      @NullableDecl Object p2) {
388    if (!expression) {
389      throw new VerifyException(format(errorMessageTemplate, p1, p2));
390    }
391  }
392
393  /**
394   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
395   * custom message otherwise.
396   *
397   * <p>See {@link #verify(boolean, String, Object...)} for details.
398   *
399   * @since 23.1 (varargs overload since 17.0)
400   */
401  public static void verify(
402      boolean expression,
403      @NullableDecl String errorMessageTemplate,
404      int p1,
405      @NullableDecl Object p2) {
406    if (!expression) {
407      throw new VerifyException(format(errorMessageTemplate, p1, p2));
408    }
409  }
410
411  /**
412   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
413   * custom message otherwise.
414   *
415   * <p>See {@link #verify(boolean, String, Object...)} for details.
416   *
417   * @since 23.1 (varargs overload since 17.0)
418   */
419  public static void verify(
420      boolean expression,
421      @NullableDecl String errorMessageTemplate,
422      long p1,
423      @NullableDecl Object p2) {
424    if (!expression) {
425      throw new VerifyException(format(errorMessageTemplate, p1, p2));
426    }
427  }
428
429  /**
430   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
431   * custom message otherwise.
432   *
433   * <p>See {@link #verify(boolean, String, Object...)} for details.
434   *
435   * @since 23.1 (varargs overload since 17.0)
436   */
437  public static void verify(
438      boolean expression,
439      @NullableDecl String errorMessageTemplate,
440      @NullableDecl Object p1,
441      @NullableDecl Object p2) {
442    if (!expression) {
443      throw new VerifyException(format(errorMessageTemplate, p1, p2));
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      @NullableDecl String errorMessageTemplate,
458      @NullableDecl Object p1,
459      @NullableDecl Object p2,
460      @NullableDecl Object p3) {
461    if (!expression) {
462      throw new VerifyException(format(errorMessageTemplate, p1, p2, p3));
463    }
464  }
465
466  /**
467   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
468   * custom message otherwise.
469   *
470   * <p>See {@link #verify(boolean, String, Object...)} for details.
471   *
472   * @since 23.1 (varargs overload since 17.0)
473   */
474  public static void verify(
475      boolean expression,
476      @NullableDecl String errorMessageTemplate,
477      @NullableDecl Object p1,
478      @NullableDecl Object p2,
479      @NullableDecl Object p3,
480      @NullableDecl Object p4) {
481    if (!expression) {
482      throw new VerifyException(format(errorMessageTemplate, p1, p2, p3, p4));
483    }
484  }
485
486  /**
487   * Ensures that {@code reference} is non-null, throwing a {@code VerifyException} with a default
488   * message otherwise.
489   *
490   * @return {@code reference}, guaranteed to be non-null, for convenience
491   * @throws VerifyException if {@code reference} is {@code null}
492   * @see Preconditions#checkNotNull Preconditions.checkNotNull()
493   */
494  @CanIgnoreReturnValue
495  public static <T> T verifyNotNull(@NullableDecl T reference) {
496    return verifyNotNull(reference, "expected a non-null reference");
497  }
498
499  /**
500   * Ensures that {@code reference} is non-null, throwing a {@code VerifyException} with a custom
501   * message otherwise.
502   *
503   * @param errorMessageTemplate a template for the exception message should the check fail. The
504   *     message is formed by replacing each {@code %s} placeholder in the template with an
505   *     argument. These are matched by position - the first {@code %s} gets {@code
506   *     errorMessageArgs[0]}, etc. Unmatched arguments will be appended to the formatted message in
507   *     square braces. Unmatched placeholders will be left as-is.
508   * @param errorMessageArgs the arguments to be substituted into the message template. Arguments
509   *     are converted to strings using {@link String#valueOf(Object)}.
510   * @return {@code reference}, guaranteed to be non-null, for convenience
511   * @throws VerifyException if {@code reference} is {@code null}
512   * @see Preconditions#checkNotNull Preconditions.checkNotNull()
513   */
514  @CanIgnoreReturnValue
515  public static <T> T verifyNotNull(
516      @NullableDecl T reference,
517      @NullableDecl String errorMessageTemplate,
518      @NullableDecl Object... errorMessageArgs) {
519    verify(reference != null, errorMessageTemplate, errorMessageArgs);
520    return reference;
521  }
522
523  // TODO(kevinb): consider <T> T verifySingleton(Iterable<T>) to take over for
524  // Iterables.getOnlyElement()
525
526  private Verify() {}
527}