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.Strings.lenientFormat;
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="https://docs.oracle.com/javase/8/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}, {@code Verify} uses {@link Strings#lenientFormat} to format
076 * error message template strings. This only supports the {@code "%s"} specifier, not the full range
077 * of {@link java.util.Formatter} specifiers. However, note that if the number of arguments does not
078 * match the number of occurrences of {@code "%s"} in the format string, {@code Verify} will still
079 * behave as expected, and will still include all argument values in the error message; the message
080 * will simply not be formatted exactly as intended.
081 *
082 * <h3>More information</h3>
083 *
084 * See <a href="https://github.com/google/guava/wiki/ConditionalFailuresExplained">Conditional
085 * failures explained</a> in the Guava User Guide for advice on when this class should be used.
086 *
087 * @since 17.0
088 */
089@GwtCompatible
090public final class Verify {
091  /**
092   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with no
093   * message otherwise.
094   *
095   * @throws VerifyException if {@code expression} is {@code false}
096   * @see Preconditions#checkState Preconditions.checkState()
097   */
098  public static void verify(boolean expression) {
099    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 {@code
112   *     errorMessageArgs[0]}, etc. Unmatched arguments will be appended to the formatted message in
113   *     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      @NullableDecl String errorMessageTemplate,
122      @NullableDecl Object... errorMessageArgs) {
123    if (!expression) {
124      throw new VerifyException(lenientFormat(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(
137      boolean expression, @NullableDecl String errorMessageTemplate, char p1) {
138    if (!expression) {
139      throw new VerifyException(lenientFormat(errorMessageTemplate, p1));
140    }
141  }
142
143  /**
144   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
145   * custom message otherwise.
146   *
147   * <p>See {@link #verify(boolean, String, Object...)} for details.
148   *
149   * @since 23.1 (varargs overload since 17.0)
150   */
151  public static void verify(boolean expression, @NullableDecl String errorMessageTemplate, int p1) {
152    if (!expression) {
153      throw new VerifyException(lenientFormat(errorMessageTemplate, p1));
154    }
155  }
156
157  /**
158   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
159   * custom message otherwise.
160   *
161   * <p>See {@link #verify(boolean, String, Object...)} for details.
162   *
163   * @since 23.1 (varargs overload since 17.0)
164   */
165  public static void verify(
166      boolean expression, @NullableDecl 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, @NullableDecl String errorMessageTemplate, @NullableDecl 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(
196      boolean expression, @NullableDecl String errorMessageTemplate, char p1, char p2) {
197    if (!expression) {
198      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
199    }
200  }
201
202  /**
203   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
204   * custom message otherwise.
205   *
206   * <p>See {@link #verify(boolean, String, Object...)} for details.
207   *
208   * @since 23.1 (varargs overload since 17.0)
209   */
210  public static void verify(
211      boolean expression, @NullableDecl String errorMessageTemplate, int p1, char p2) {
212    if (!expression) {
213      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
214    }
215  }
216
217  /**
218   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
219   * custom message otherwise.
220   *
221   * <p>See {@link #verify(boolean, String, Object...)} for details.
222   *
223   * @since 23.1 (varargs overload since 17.0)
224   */
225  public static void verify(
226      boolean expression, @NullableDecl String errorMessageTemplate, long p1, char p2) {
227    if (!expression) {
228      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
229    }
230  }
231
232  /**
233   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
234   * custom message otherwise.
235   *
236   * <p>See {@link #verify(boolean, String, Object...)} for details.
237   *
238   * @since 23.1 (varargs overload since 17.0)
239   */
240  public static void verify(
241      boolean expression,
242      @NullableDecl String errorMessageTemplate,
243      @NullableDecl Object p1,
244      char p2) {
245    if (!expression) {
246      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
247    }
248  }
249
250  /**
251   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
252   * custom message otherwise.
253   *
254   * <p>See {@link #verify(boolean, String, Object...)} for details.
255   *
256   * @since 23.1 (varargs overload since 17.0)
257   */
258  public static void verify(
259      boolean expression, @NullableDecl String errorMessageTemplate, char p1, int p2) {
260    if (!expression) {
261      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
262    }
263  }
264
265  /**
266   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
267   * custom message otherwise.
268   *
269   * <p>See {@link #verify(boolean, String, Object...)} for details.
270   *
271   * @since 23.1 (varargs overload since 17.0)
272   */
273  public static void verify(
274      boolean expression, @NullableDecl String errorMessageTemplate, int p1, int p2) {
275    if (!expression) {
276      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
277    }
278  }
279
280  /**
281   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
282   * custom message otherwise.
283   *
284   * <p>See {@link #verify(boolean, String, Object...)} for details.
285   *
286   * @since 23.1 (varargs overload since 17.0)
287   */
288  public static void verify(
289      boolean expression, @NullableDecl String errorMessageTemplate, long p1, int p2) {
290    if (!expression) {
291      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
292    }
293  }
294
295  /**
296   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
297   * custom message otherwise.
298   *
299   * <p>See {@link #verify(boolean, String, Object...)} for details.
300   *
301   * @since 23.1 (varargs overload since 17.0)
302   */
303  public static void verify(
304      boolean expression,
305      @NullableDecl String errorMessageTemplate,
306      @NullableDecl Object p1,
307      int p2) {
308    if (!expression) {
309      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
310    }
311  }
312
313  /**
314   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
315   * custom message otherwise.
316   *
317   * <p>See {@link #verify(boolean, String, Object...)} for details.
318   *
319   * @since 23.1 (varargs overload since 17.0)
320   */
321  public static void verify(
322      boolean expression, @NullableDecl String errorMessageTemplate, char p1, long p2) {
323    if (!expression) {
324      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
325    }
326  }
327
328  /**
329   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
330   * custom message otherwise.
331   *
332   * <p>See {@link #verify(boolean, String, Object...)} for details.
333   *
334   * @since 23.1 (varargs overload since 17.0)
335   */
336  public static void verify(
337      boolean expression, @NullableDecl String errorMessageTemplate, int 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, @NullableDecl String errorMessageTemplate, long 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,
368      @NullableDecl String errorMessageTemplate,
369      @NullableDecl Object p1,
370      long p2) {
371    if (!expression) {
372      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
373    }
374  }
375
376  /**
377   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
378   * custom message otherwise.
379   *
380   * <p>See {@link #verify(boolean, String, Object...)} for details.
381   *
382   * @since 23.1 (varargs overload since 17.0)
383   */
384  public static void verify(
385      boolean expression,
386      @NullableDecl String errorMessageTemplate,
387      char p1,
388      @NullableDecl Object p2) {
389    if (!expression) {
390      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
391    }
392  }
393
394  /**
395   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
396   * custom message otherwise.
397   *
398   * <p>See {@link #verify(boolean, String, Object...)} for details.
399   *
400   * @since 23.1 (varargs overload since 17.0)
401   */
402  public static void verify(
403      boolean expression,
404      @NullableDecl String errorMessageTemplate,
405      int p1,
406      @NullableDecl Object p2) {
407    if (!expression) {
408      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
409    }
410  }
411
412  /**
413   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
414   * custom message otherwise.
415   *
416   * <p>See {@link #verify(boolean, String, Object...)} for details.
417   *
418   * @since 23.1 (varargs overload since 17.0)
419   */
420  public static void verify(
421      boolean expression,
422      @NullableDecl String errorMessageTemplate,
423      long p1,
424      @NullableDecl Object p2) {
425    if (!expression) {
426      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
427    }
428  }
429
430  /**
431   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
432   * custom message otherwise.
433   *
434   * <p>See {@link #verify(boolean, String, Object...)} for details.
435   *
436   * @since 23.1 (varargs overload since 17.0)
437   */
438  public static void verify(
439      boolean expression,
440      @NullableDecl String errorMessageTemplate,
441      @NullableDecl Object p1,
442      @NullableDecl Object p2) {
443    if (!expression) {
444      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
445    }
446  }
447
448  /**
449   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
450   * custom message otherwise.
451   *
452   * <p>See {@link #verify(boolean, String, Object...)} for details.
453   *
454   * @since 23.1 (varargs overload since 17.0)
455   */
456  public static void verify(
457      boolean expression,
458      @NullableDecl String errorMessageTemplate,
459      @NullableDecl Object p1,
460      @NullableDecl Object p2,
461      @NullableDecl Object p3) {
462    if (!expression) {
463      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2, p3));
464    }
465  }
466
467  /**
468   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
469   * custom message otherwise.
470   *
471   * <p>See {@link #verify(boolean, String, Object...)} for details.
472   *
473   * @since 23.1 (varargs overload since 17.0)
474   */
475  public static void verify(
476      boolean expression,
477      @NullableDecl String errorMessageTemplate,
478      @NullableDecl Object p1,
479      @NullableDecl Object p2,
480      @NullableDecl Object p3,
481      @NullableDecl Object p4) {
482    if (!expression) {
483      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2, p3, p4));
484    }
485  }
486
487  /**
488   * Ensures that {@code reference} is non-null, throwing a {@code VerifyException} with a default
489   * message otherwise.
490   *
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(@NullableDecl T reference) {
497    return verifyNotNull(reference, "expected a non-null reference");
498  }
499
500  /**
501   * Ensures that {@code reference} is non-null, throwing a {@code VerifyException} with a custom
502   * message otherwise.
503   *
504   * @param errorMessageTemplate a template for the exception message should the check fail. The
505   *     message is formed by replacing each {@code %s} placeholder in the template with an
506   *     argument. These are matched by position - the first {@code %s} gets {@code
507   *     errorMessageArgs[0]}, etc. Unmatched arguments will be appended to the formatted message in
508   *     square braces. Unmatched placeholders will be left as-is.
509   * @param errorMessageArgs the arguments to be substituted into the message template. Arguments
510   *     are converted to strings using {@link String#valueOf(Object)}.
511   * @return {@code reference}, guaranteed to be non-null, for convenience
512   * @throws VerifyException if {@code reference} is {@code null}
513   * @see Preconditions#checkNotNull Preconditions.checkNotNull()
514   */
515  @CanIgnoreReturnValue
516  public static <T> T verifyNotNull(
517      @NullableDecl T reference,
518      @NullableDecl String errorMessageTemplate,
519      @NullableDecl Object... errorMessageArgs) {
520    verify(reference != null, errorMessageTemplate, errorMessageArgs);
521    return reference;
522  }
523
524  // TODO(kevinb): consider <T> T verifySingleton(Iterable<T>) to take over for
525  // Iterables.getOnlyElement()
526
527  private Verify() {}
528}