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.jspecify.annotations.Nullable;
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      String errorMessageTemplate,
122      @Nullable Object @Nullable ... 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(boolean expression, String errorMessageTemplate, char p1) {
137    if (!expression) {
138      throw new VerifyException(lenientFormat(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, String errorMessageTemplate, int p1) {
151    if (!expression) {
152      throw new VerifyException(lenientFormat(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, String errorMessageTemplate, long p1) {
165    if (!expression) {
166      throw new VerifyException(lenientFormat(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(boolean expression, String errorMessageTemplate, @Nullable Object p1) {
179    if (!expression) {
180      throw new VerifyException(lenientFormat(errorMessageTemplate, p1));
181    }
182  }
183
184  /**
185   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
186   * custom message otherwise.
187   *
188   * <p>See {@link #verify(boolean, String, Object...)} for details.
189   *
190   * @since 23.1 (varargs overload since 17.0)
191   */
192  public static void verify(boolean expression, String errorMessageTemplate, char p1, char p2) {
193    if (!expression) {
194      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
195    }
196  }
197
198  /**
199   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
200   * custom message otherwise.
201   *
202   * <p>See {@link #verify(boolean, String, Object...)} for details.
203   *
204   * @since 23.1 (varargs overload since 17.0)
205   */
206  public static void verify(boolean expression, String errorMessageTemplate, int p1, char p2) {
207    if (!expression) {
208      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
209    }
210  }
211
212  /**
213   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
214   * custom message otherwise.
215   *
216   * <p>See {@link #verify(boolean, String, Object...)} for details.
217   *
218   * @since 23.1 (varargs overload since 17.0)
219   */
220  public static void verify(boolean expression, String errorMessageTemplate, long p1, char p2) {
221    if (!expression) {
222      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
223    }
224  }
225
226  /**
227   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
228   * custom message otherwise.
229   *
230   * <p>See {@link #verify(boolean, String, Object...)} for details.
231   *
232   * @since 23.1 (varargs overload since 17.0)
233   */
234  public static void verify(
235      boolean expression, String errorMessageTemplate, @Nullable Object p1, char p2) {
236    if (!expression) {
237      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
238    }
239  }
240
241  /**
242   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
243   * custom message otherwise.
244   *
245   * <p>See {@link #verify(boolean, String, Object...)} for details.
246   *
247   * @since 23.1 (varargs overload since 17.0)
248   */
249  public static void verify(boolean expression, String errorMessageTemplate, char p1, int p2) {
250    if (!expression) {
251      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
252    }
253  }
254
255  /**
256   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
257   * custom message otherwise.
258   *
259   * <p>See {@link #verify(boolean, String, Object...)} for details.
260   *
261   * @since 23.1 (varargs overload since 17.0)
262   */
263  public static void verify(boolean expression, String errorMessageTemplate, int p1, int p2) {
264    if (!expression) {
265      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
266    }
267  }
268
269  /**
270   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
271   * custom message otherwise.
272   *
273   * <p>See {@link #verify(boolean, String, Object...)} for details.
274   *
275   * @since 23.1 (varargs overload since 17.0)
276   */
277  public static void verify(boolean expression, String errorMessageTemplate, long p1, int p2) {
278    if (!expression) {
279      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
280    }
281  }
282
283  /**
284   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
285   * custom message otherwise.
286   *
287   * <p>See {@link #verify(boolean, String, Object...)} for details.
288   *
289   * @since 23.1 (varargs overload since 17.0)
290   */
291  public static void verify(
292      boolean expression, String errorMessageTemplate, @Nullable Object p1, int p2) {
293    if (!expression) {
294      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
295    }
296  }
297
298  /**
299   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
300   * custom message otherwise.
301   *
302   * <p>See {@link #verify(boolean, String, Object...)} for details.
303   *
304   * @since 23.1 (varargs overload since 17.0)
305   */
306  public static void verify(boolean expression, String errorMessageTemplate, char p1, long p2) {
307    if (!expression) {
308      throw new VerifyException(lenientFormat(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(boolean expression, String errorMessageTemplate, int p1, long p2) {
321    if (!expression) {
322      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
323    }
324  }
325
326  /**
327   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
328   * custom message otherwise.
329   *
330   * <p>See {@link #verify(boolean, String, Object...)} for details.
331   *
332   * @since 23.1 (varargs overload since 17.0)
333   */
334  public static void verify(boolean expression, String errorMessageTemplate, long p1, long p2) {
335    if (!expression) {
336      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
337    }
338  }
339
340  /**
341   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
342   * custom message otherwise.
343   *
344   * <p>See {@link #verify(boolean, String, Object...)} for details.
345   *
346   * @since 23.1 (varargs overload since 17.0)
347   */
348  public static void verify(
349      boolean expression, String errorMessageTemplate, @Nullable Object p1, long p2) {
350    if (!expression) {
351      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
352    }
353  }
354
355  /**
356   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
357   * custom message otherwise.
358   *
359   * <p>See {@link #verify(boolean, String, Object...)} for details.
360   *
361   * @since 23.1 (varargs overload since 17.0)
362   */
363  public static void verify(
364      boolean expression, String errorMessageTemplate, char p1, @Nullable Object p2) {
365    if (!expression) {
366      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
367    }
368  }
369
370  /**
371   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
372   * custom message otherwise.
373   *
374   * <p>See {@link #verify(boolean, String, Object...)} for details.
375   *
376   * @since 23.1 (varargs overload since 17.0)
377   */
378  public static void verify(
379      boolean expression, String errorMessageTemplate, int p1, @Nullable Object p2) {
380    if (!expression) {
381      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
382    }
383  }
384
385  /**
386   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
387   * custom message otherwise.
388   *
389   * <p>See {@link #verify(boolean, String, Object...)} for details.
390   *
391   * @since 23.1 (varargs overload since 17.0)
392   */
393  public static void verify(
394      boolean expression, String errorMessageTemplate, long p1, @Nullable Object p2) {
395    if (!expression) {
396      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
397    }
398  }
399
400  /**
401   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
402   * custom message otherwise.
403   *
404   * <p>See {@link #verify(boolean, String, Object...)} for details.
405   *
406   * @since 23.1 (varargs overload since 17.0)
407   */
408  public static void verify(
409      boolean expression, String errorMessageTemplate, @Nullable Object p1, @Nullable Object p2) {
410    if (!expression) {
411      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2));
412    }
413  }
414
415  /**
416   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
417   * custom message otherwise.
418   *
419   * <p>See {@link #verify(boolean, String, Object...)} for details.
420   *
421   * @since 23.1 (varargs overload since 17.0)
422   */
423  public static void verify(
424      boolean expression,
425      String errorMessageTemplate,
426      @Nullable Object p1,
427      @Nullable Object p2,
428      @Nullable Object p3) {
429    if (!expression) {
430      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2, p3));
431    }
432  }
433
434  /**
435   * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a
436   * custom message otherwise.
437   *
438   * <p>See {@link #verify(boolean, String, Object...)} for details.
439   *
440   * @since 23.1 (varargs overload since 17.0)
441   */
442  public static void verify(
443      boolean expression,
444      String errorMessageTemplate,
445      @Nullable Object p1,
446      @Nullable Object p2,
447      @Nullable Object p3,
448      @Nullable Object p4) {
449    if (!expression) {
450      throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2, p3, p4));
451    }
452  }
453
454  /*
455   * For a discussion of the signature of verifyNotNull, see the discussion above
456   * Preconditions.checkNotNull.
457   *
458   * (verifyNotNull has many fewer "problem" callers, so we could try to be stricter. On the other
459   * hand, verifyNotNull arguably has more reason to accept nullable arguments in the first
460   * place....)
461   */
462
463  /**
464   * Ensures that {@code reference} is non-null, throwing a {@code VerifyException} with a default
465   * message otherwise.
466   *
467   * @return {@code reference}, guaranteed to be non-null, for convenience
468   * @throws VerifyException if {@code reference} is {@code null}
469   * @see Preconditions#checkNotNull Preconditions.checkNotNull()
470   */
471  @CanIgnoreReturnValue
472  public static <T> T verifyNotNull(@Nullable T reference) {
473    return verifyNotNull(reference, "expected a non-null reference");
474  }
475
476  /**
477   * Ensures that {@code reference} is non-null, throwing a {@code VerifyException} with a custom
478   * message otherwise.
479   *
480   * @param errorMessageTemplate a template for the exception message should the check fail. The
481   *     message is formed by replacing each {@code %s} placeholder in the template with an
482   *     argument. These are matched by position - the first {@code %s} gets {@code
483   *     errorMessageArgs[0]}, etc. Unmatched arguments will be appended to the formatted message in
484   *     square braces. Unmatched placeholders will be left as-is.
485   * @param errorMessageArgs the arguments to be substituted into the message template. Arguments
486   *     are converted to strings using {@link String#valueOf(Object)}.
487   * @return {@code reference}, guaranteed to be non-null, for convenience
488   * @throws VerifyException if {@code reference} is {@code null}
489   * @see Preconditions#checkNotNull Preconditions.checkNotNull()
490   */
491  @CanIgnoreReturnValue
492  public static <T> T verifyNotNull(
493      @Nullable T reference,
494      String errorMessageTemplate,
495      @Nullable Object @Nullable ... errorMessageArgs) {
496    if (reference == null) {
497      throw new VerifyException(lenientFormat(errorMessageTemplate, errorMessageArgs));
498    }
499    return reference;
500  }
501
502  // TODO(kevinb): consider <T> T verifySingleton(Iterable<T>) to take over for
503  // Iterables.getOnlyElement()
504
505  private Verify() {}
506}