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() {}
}