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.qual.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      @Nullable 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, @Nullable 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, @Nullable 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, @Nullable 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(
179      boolean expression, @Nullable String errorMessageTemplate, @Nullable Object p1) {
180    if (!expression) {
181      throw new VerifyException(lenientFormat(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(lenientFormat(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(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(
224      boolean expression, @Nullable String errorMessageTemplate, long p1, char p2) {
225    if (!expression) {
226      throw new VerifyException(lenientFormat(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(lenientFormat(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(lenientFormat(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(lenientFormat(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(lenientFormat(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(lenientFormat(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(lenientFormat(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(lenientFormat(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(lenientFormat(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(lenientFormat(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(lenientFormat(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(lenientFormat(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(lenientFormat(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(lenientFormat(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(lenientFormat(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(lenientFormat(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 {@code
487   *     errorMessageArgs[0]}, etc. Unmatched arguments will be appended to the formatted message in
488   *     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 @Nullable... 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}