| /* |
| * Copyright (C) 2013 The Guava Authors |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except |
| * in compliance with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software distributed under the License |
| * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express |
| * or implied. See the License for the specific language governing permissions and limitations under |
| * the License. |
| */ |
| |
| package com.google.common.base; |
| |
| import static com.google.common.base.Strings.lenientFormat; |
| |
| import com.google.common.annotations.GwtCompatible; |
| import com.google.errorprone.annotations.CanIgnoreReturnValue; |
| import org.checkerframework.checker.nullness.compatqual.NullableDecl; |
| |
| /** |
| * Static convenience methods that serve the same purpose as Java language <a |
| * href="https://docs.oracle.com/javase/8/docs/technotes/guides/language/assert.html">assertions</a>, |
| * except that they are always enabled. These methods should be used instead of Java assertions |
| * whenever there is a chance the check may fail "in real life". Example: |
| * |
| * <pre>{@code |
| * Bill bill = remoteService.getLastUnpaidBill(); |
| * |
| * // In case bug 12345 happens again we'd rather just die |
| * Verify.verify(bill.status() == Status.UNPAID, |
| * "Unexpected bill status: %s", bill.status()); |
| * }</pre> |
| * |
| * <h3>Comparison to alternatives</h3> |
| * |
| * <p><b>Note:</b> In some cases the differences explained below can be subtle. When it's unclear |
| * which approach to use, <b>don't worry</b> too much about it; just pick something that seems |
| * reasonable and it will be fine. |
| * |
| * <ul> |
| * <li>If checking whether the <i>caller</i> has violated your method or constructor's contract |
| * (such as by passing an invalid argument), use the utilities of the {@link Preconditions} |
| * class instead. |
| * <li>If checking an <i>impossible</i> condition (which <i>cannot</i> happen unless your own |
| * class or its <i>trusted</i> dependencies is badly broken), this is what ordinary Java |
| * assertions are for. Note that assertions are not enabled by default; they are essentially |
| * considered "compiled comments." |
| * <li>An explicit {@code if/throw} (as illustrated below) is always acceptable; we still |
| * recommend using our {@link VerifyException} exception type. Throwing a plain {@link |
| * RuntimeException} is frowned upon. |
| * <li>Use of {@link java.util.Objects#requireNonNull(Object)} is generally discouraged, since |
| * {@link #verifyNotNull(Object)} and {@link Preconditions#checkNotNull(Object)} perform the |
| * same function with more clarity. |
| * </ul> |
| * |
| * <h3>Warning about performance</h3> |
| * |
| * <p>Remember that parameter values for message construction must all be computed eagerly, and |
| * autoboxing and varargs array creation may happen as well, even when the verification succeeds and |
| * the message ends up unneeded. Performance-sensitive verification checks should continue to use |
| * usual form: |
| * |
| * <pre>{@code |
| * Bill bill = remoteService.getLastUnpaidBill(); |
| * if (bill.status() != Status.UNPAID) { |
| * throw new VerifyException("Unexpected bill status: " + bill.status()); |
| * } |
| * }</pre> |
| * |
| * <h3>Only {@code %s} is supported</h3> |
| * |
| * <p>As with {@link Preconditions}, {@code Verify} uses {@link Strings#lenientFormat} to format |
| * error message template strings. This only supports the {@code "%s"} specifier, not the full range |
| * of {@link java.util.Formatter} specifiers. However, note that if the number of arguments does not |
| * match the number of occurrences of {@code "%s"} in the format string, {@code Verify} will still |
| * behave as expected, and will still include all argument values in the error message; the message |
| * will simply not be formatted exactly as intended. |
| * |
| * <h3>More information</h3> |
| * |
| * See <a href="https://github.com/google/guava/wiki/ConditionalFailuresExplained">Conditional |
| * failures explained</a> in the Guava User Guide for advice on when this class should be used. |
| * |
| * @since 17.0 |
| */ |
| @GwtCompatible |
| public final class Verify { |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with no |
| * message otherwise. |
| * |
| * @throws VerifyException if {@code expression} is {@code false} |
| * @see Preconditions#checkState Preconditions.checkState() |
| */ |
| public static void verify(boolean expression) { |
| if (!expression) { |
| throw new VerifyException(); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * @param expression a boolean expression |
| * @param errorMessageTemplate a template for the exception message should the check fail. The |
| * message is formed by replacing each {@code %s} placeholder in the template with an |
| * argument. These are matched by position - the first {@code %s} gets {@code |
| * errorMessageArgs[0]}, etc. Unmatched arguments will be appended to the formatted message in |
| * square braces. Unmatched placeholders will be left as-is. |
| * @param errorMessageArgs the arguments to be substituted into the message template. Arguments |
| * are converted to strings using {@link String#valueOf(Object)}. |
| * @throws VerifyException if {@code expression} is {@code false} |
| * @see Preconditions#checkState Preconditions.checkState() |
| */ |
| public static void verify( |
| boolean expression, |
| @NullableDecl String errorMessageTemplate, |
| @NullableDecl Object... errorMessageArgs) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, errorMessageArgs)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, @NullableDecl String errorMessageTemplate, char p1) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify(boolean expression, @NullableDecl String errorMessageTemplate, int p1) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, @NullableDecl String errorMessageTemplate, long p1) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, @NullableDecl String errorMessageTemplate, @NullableDecl Object p1) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, @NullableDecl String errorMessageTemplate, char p1, char p2) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, @NullableDecl String errorMessageTemplate, int p1, char p2) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, @NullableDecl String errorMessageTemplate, long p1, char p2) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, |
| @NullableDecl String errorMessageTemplate, |
| @NullableDecl Object p1, |
| char p2) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, @NullableDecl String errorMessageTemplate, char p1, int p2) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, @NullableDecl String errorMessageTemplate, int p1, int p2) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, @NullableDecl String errorMessageTemplate, long p1, int p2) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, |
| @NullableDecl String errorMessageTemplate, |
| @NullableDecl Object p1, |
| int p2) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, @NullableDecl String errorMessageTemplate, char p1, long p2) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, @NullableDecl String errorMessageTemplate, int p1, long p2) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, @NullableDecl String errorMessageTemplate, long p1, long p2) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, |
| @NullableDecl String errorMessageTemplate, |
| @NullableDecl Object p1, |
| long p2) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, |
| @NullableDecl String errorMessageTemplate, |
| char p1, |
| @NullableDecl Object p2) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, |
| @NullableDecl String errorMessageTemplate, |
| int p1, |
| @NullableDecl Object p2) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, |
| @NullableDecl String errorMessageTemplate, |
| long p1, |
| @NullableDecl Object p2) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, |
| @NullableDecl String errorMessageTemplate, |
| @NullableDecl Object p1, |
| @NullableDecl Object p2) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, |
| @NullableDecl String errorMessageTemplate, |
| @NullableDecl Object p1, |
| @NullableDecl Object p2, |
| @NullableDecl Object p3) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2, p3)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code expression} is {@code true}, throwing a {@code VerifyException} with a |
| * custom message otherwise. |
| * |
| * <p>See {@link #verify(boolean, String, Object...)} for details. |
| * |
| * @since 23.1 (varargs overload since 17.0) |
| */ |
| public static void verify( |
| boolean expression, |
| @NullableDecl String errorMessageTemplate, |
| @NullableDecl Object p1, |
| @NullableDecl Object p2, |
| @NullableDecl Object p3, |
| @NullableDecl Object p4) { |
| if (!expression) { |
| throw new VerifyException(lenientFormat(errorMessageTemplate, p1, p2, p3, p4)); |
| } |
| } |
| |
| /** |
| * Ensures that {@code reference} is non-null, throwing a {@code VerifyException} with a default |
| * message otherwise. |
| * |
| * @return {@code reference}, guaranteed to be non-null, for convenience |
| * @throws VerifyException if {@code reference} is {@code null} |
| * @see Preconditions#checkNotNull Preconditions.checkNotNull() |
| */ |
| @CanIgnoreReturnValue |
| public static <T> T verifyNotNull(@NullableDecl T reference) { |
| return verifyNotNull(reference, "expected a non-null reference"); |
| } |
| |
| /** |
| * Ensures that {@code reference} is non-null, throwing a {@code VerifyException} with a custom |
| * message otherwise. |
| * |
| * @param errorMessageTemplate a template for the exception message should the check fail. The |
| * message is formed by replacing each {@code %s} placeholder in the template with an |
| * argument. These are matched by position - the first {@code %s} gets {@code |
| * errorMessageArgs[0]}, etc. Unmatched arguments will be appended to the formatted message in |
| * square braces. Unmatched placeholders will be left as-is. |
| * @param errorMessageArgs the arguments to be substituted into the message template. Arguments |
| * are converted to strings using {@link String#valueOf(Object)}. |
| * @return {@code reference}, guaranteed to be non-null, for convenience |
| * @throws VerifyException if {@code reference} is {@code null} |
| * @see Preconditions#checkNotNull Preconditions.checkNotNull() |
| */ |
| @CanIgnoreReturnValue |
| public static <T> T verifyNotNull( |
| @NullableDecl T reference, |
| @NullableDecl String errorMessageTemplate, |
| @NullableDecl Object... errorMessageArgs) { |
| verify(reference != null, errorMessageTemplate, errorMessageArgs); |
| return reference; |
| } |
| |
| // TODO(kevinb): consider <T> T verifySingleton(Iterable<T>) to take over for |
| // Iterables.getOnlyElement() |
| |
| private Verify() {} |
| } |