Static convenience methods that help a method or constructor check whether it was invoked
correctly (whether its
preconditions have been met). These methods generally accept a
boolean expression which is expected to be
true (or in the case of
checkNotNull, an object reference which is expected to be non-null). When
false (or
null) is passed instead, the
Preconditions method throws an unchecked exception,
which helps the calling method communicate to
its caller that
that caller has made
a mistake. Example:
/ /void exampleBadCaller()
double d = sqrt(-1.0);
}}
In this example,
checkArgument throws an
IllegalArgumentException to indicate
that
exampleBadCaller made an error in
its call to
sqrt.
Warning about performance
The goal of this class is to improve readability of code, but in some circumstances this may
come at a significant performance cost. 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 precondition check then succeeds (as it should almost always do in production). In some
circumstances these wasted CPU cycles and allocations can add up to a real problem.
Performance-sensitive precondition checks can always be converted to the customary form:
if (value < 0.0)
Other types of preconditions
Not every type of precondition failure is supported by these methods. Continue to throw
standard JDK exceptions such as
java.util.NoSuchElementException or
UnsupportedOperationException in the situations they are intended for.
Non-preconditions
It is of course possible to use the methods of this class to check for invalid conditions
which are not the caller's fault. Doing so is not recommended because it is
misleading to future readers of the code and of stack traces. See
Conditional
failures explained in the Guava User Guide for more advice.
java.util.Objects.requireNonNull()
Projects which use
com.google.common should generally avoid the use of
java.util.Objects#requireNonNull(Object). Instead, use whichever of
#checkNotNull(Object) or
Verify#verifyNotNull(Object) is appropriate to the situation.
(The same goes for the message-accepting overloads.)
Only
%s is supported
In
Preconditions error message template strings, only the
"%s" specifier is
supported, not the full range of
java.util.Formatter specifiers.
More information
See the Guava User Guide on
using
Preconditions.