All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.google.common.base.Verify Maven / Gradle / Ivy

/*
 * 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 assertions,
 * 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:
 *
 * 
{@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());
 * }
* *

Comparison to alternatives

* *

Note: In some cases the differences explained below can be subtle. When it's unclear * which approach to use, don't worry too much about it; just pick something that seems * reasonable and it will be fine. * *

    *
  • If checking whether the caller has violated your method or constructor's contract * (such as by passing an invalid argument), use the utilities of the {@link Preconditions} * class instead. *
  • If checking an impossible condition (which cannot happen unless your own * class or its trusted 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." *
  • 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. *
  • 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. *
* *

Warning about performance

* *

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: * *

{@code
 * Bill bill = remoteService.getLastUnpaidBill();
 * if (bill.status() != Status.UNPAID) {
 *   throw new VerifyException("Unexpected bill status: " + bill.status());
 * }
 * }
* *

Only {@code %s} is supported

* *

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. * *

More information

* * See Conditional * failures explained 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. * *

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. * *

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. * *

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. * *

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. * *

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. * *

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. * *

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. * *

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. * *

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. * *

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. * *

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. * *

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. * *

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. * *

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. * *

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. * *

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. * *

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. * *

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. * *

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. * *

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. * *

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. * *

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 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 verifyNotNull( @NullableDecl T reference, @NullableDecl String errorMessageTemplate, @NullableDecl Object... errorMessageArgs) { verify(reference != null, errorMessageTemplate, errorMessageArgs); return reference; } // TODO(kevinb): consider T verifySingleton(Iterable) to take over for // Iterables.getOnlyElement() private Verify() {} }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy