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 javax.annotation.CheckForNull;
022import org.checkerframework.checker.nullness.qual.Nullable;
023
024/**
025 * Static convenience methods that serve the same purpose as Java language <a
026 * href="https://docs.oracle.com/javase/8/docs/technotes/guides/language/assert.html">assertions</a>,
027 * except that they are always enabled. These methods should be used instead of Java assertions
028 * whenever there is a chance the check may fail "in real life". Example:
029 *
030 * <pre>{@code
031 * Bill bill = remoteService.getLastUnpaidBill();
032 *
033 * // In case bug 12345 happens again we'd rather just die
034 * Verify.verify(bill.status() == Status.UNPAID,
035 *     "Unexpected bill status: %s", bill.status());
036 * }</pre>
037 *
038 * <h3>Comparison to alternatives</h3>
039 *
040 * <p><b>Note:</b> In some cases the differences explained below can be subtle. When it's unclear
041 * which approach to use, <b>don't worry</b> too much about it; just pick something that seems
042 * reasonable and it will be fine.
043 *
044 * <ul>
045 *   <li>If checking whether the <i>caller</i> has violated your method or constructor's contract
046 *       (such as by passing an invalid argument), use the utilities of the {@link Preconditions}
047 *       class instead.
048 *   <li>If checking an <i>impossible</i> condition (which <i>cannot</i> happen unless your own
049 *       class or its <i>trusted</i> dependencies is badly broken), this is what ordinary Java
050 *       assertions are for. Note that assertions are not enabled by default; they are essentially
051 *       considered "compiled comments."
052 *   <li>An explicit {@code if/throw} (as illustrated below) is always acceptable; we still
053 *       recommend using our {@link VerifyException} exception type. Throwing a plain {@link
054 *       RuntimeException} is frowned upon.
055 *   <li>Use of {@link java.util.Objects#requireNonNull(Object)} is generally discouraged, since
056 *       {@link #verifyNotNull(Object)} and {@link Preconditions#checkNotNull(Object)} perform the
057 *       same function with more clarity.
058 * </ul>
059 *
060 * <h3>Warning about performance</h3>
061 *
062 * <p>Remember that parameter values for message construction must all be computed eagerly, and
063 * autoboxing and varargs array creation may happen as well, even when the verification succeeds and
064 * the message ends up unneeded. Performance-sensitive verification checks should continue to use
065 * usual form:
066 *
067 * <pre>{@code
068 * Bill bill = remoteService.getLastUnpaidBill();
069 * if (bill.status() != Status.UNPAID) {
070 *   throw new VerifyException("Unexpected bill status: " + bill.status());
071 * }
072 * }</pre>
073 *
074 * <h3>Only {@code %s} is supported</h3>
075 *
076 * <p>As with {@link Preconditions}, {@code Verify} uses {@link Strings#lenientFormat} to format
077 * error message template strings. This only supports the {@code "%s"} specifier, not the full range
078 * of {@link java.util.Formatter} specifiers. However, note that if the number of arguments does not
079 * match the number of occurrences of {@code "%s"} in the format string, {@code Verify} will still
080 * behave as expected, and will still include all argument values in the error message; the message
081 * will simply not be formatted exactly as intended.
082 *
083 * <h3>More information</h3>
084 *
085 * See <a href="https://github.com/google/guava/wiki/ConditionalFailuresExplained">Conditional
086 * failures explained</a> in the Guava User Guide for advice on when this class should be used.
087 *
088 * @since 17.0
089 */
090@GwtCompatible
091@ElementTypesAreNonnullByDefault
092public final class Verify {
093  /**
094   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with no
095   * message otherwise.
096   *
097   * @throws VerifyException if {@code expression} is {@code false}
098   * @see Preconditions#checkState Preconditions.checkState()
099   */
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}