com.google.common.base
Class Preconditions

java.lang.Object
  com.google.common.base.Preconditions

public final class Preconditions
extends Object

Contains static methods that can be called at the start of your methods to verify correct arguments and state. Note that the standard Java idiom is to use the following directly:

   if (!argumentAssumption) {
     throw new IllegalArgumentException();
   }
   if (!stateAssumption) {
     throw new IllegalStateException();
   }
   if (requiredArgument == null) {
     throw new NullPointerException();
   }
 

It is perfectly acceptable to stick to the standard idiom. There are two primary reasons you might prefer to use this class instead. First, it is significantly more compact (especially if you use static import, but even if you don't).

Moreover, Preconditions goes to a little extra effort to highlight for you what it thinks (heuristically) are the two key frames of the stack trace. First is the line that identifies which precondition check failed. Second is the line of the most likely "offender", which is defined as the first frame in the stack trace that comes from a different class from the class checking the precondition. Example message:

 java.lang.IllegalArgumentException: precondition failed: (your message here)
     failed check:   at somepackage.SomeClass.someMethod(SomeClass.java:101)
     offending call: at otherpackage.Caller.callingMethod(Caller.java:99)
 

(Again, the above is only the exception message, and the full stack trace is kept intact.)

Author:

Kevin Bourrillion

Method Summary

static void	checkArgument(boolean expression) Ensures that expression is true.
static void	checkArgument(boolean expression, Object message) Ensures that expression is true.
static void	checkArgument(boolean expression, String errorFormat, Object... args) Ensures that expression is true.
static <T extends Iterable<?>> T	checkContentsNotNull(T iterable) Ensures that iterable is not null and that it contains no null elements.
static <T> T	checkNotNull(T reference) Ensures that reference is not null.
static <T> T	checkNotNull(T reference, Object message) Ensures that reference is not null.
static <T> T	checkNotNull(T reference, String errorFormat, Object... args) Ensures that reference is not null.
static void	checkState(boolean expression) Ensures that expression is true.
static void	checkState(boolean expression, Object message) Ensures that expression is true.
static void	checkState(boolean expression, String errorFormat, Object... args) Ensures that expression is true.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

checkArgument

public static void checkArgument(boolean expression)

Ensures that expression is true.

Parameters:

expression - any boolean expression involving an argument to the current method

Throws:

IllegalArgumentException - if expression is false

checkState

public static void checkState(boolean expression)

Ensures that expression is true.

Parameters:

expression - any boolean expression involving the state of the current instance (and not involving arguments)

Throws:

IllegalStateException - if expression is false

checkNotNull

public static <T> T checkNotNull(T reference)

Ensures that reference is not null.

Parameters:

reference - an object reference that was passed as a parameter to the current method

Returns:

the non-null reference that was validated

Throws:

NullPointerException - if reference is null

checkArgument

public static void checkArgument(boolean expression,
                                 Object message)

Ensures that expression is true.

Parameters:

expression - any boolean expression involving an argument to the current method

message - a message object which will be converted using Object#toString and included in the exception message if the check fails

Throws:

IllegalArgumentException - if expression is false

checkState

public static void checkState(boolean expression,
                              Object message)

Ensures that expression is true.

Parameters:

expression - any boolean expression involving the state of the current instance (and not involving arguments)

message - a message object which will be converted using Object#toString and included in the exception message if the check fails

Throws:

IllegalStateException - if expression is false

checkNotNull

public static <T> T checkNotNull(T reference,
                                 Object message)

Ensures that reference is not null.

Parameters:

reference - an object reference that was passed as a parameter to the current method

message - a message object which will be converted using Object#toString and included in the exception message if the check fails

Returns:

the non-null reference that was validated

Throws:

NullPointerException - if reference is null

checkContentsNotNull

public static <T extends Iterable<?>> T checkContentsNotNull(T iterable)

Ensures that iterable is not null and that it contains no null elements.

Parameters:

iterable - the Iterable to check for nullness

Returns:

iterable if not null

Throws:

NullPointerException - if iterable is null, or if it contains any null elements

checkArgument

public static void checkArgument(boolean expression,
                                 String errorFormat,
                                 Object... args)

Ensures that expression is true.

Parameters:

expression - any boolean expression involving an argument to the current method

errorFormat - format of error message to produce if the check fails

args - the arguments for errorFormat

Throws:

IllegalArgumentException - if expression is false

See Also:

Format string syntax

checkState

public static void checkState(boolean expression,
                              String errorFormat,
                              Object... args)

Ensures that expression is true.

Parameters:

expression - any boolean expression involving the state of the current instance (and not involving arguments)

errorFormat - format of error message to produce if the check fails

args - the arguments for errorFormat

Throws:

IllegalStateException - if errorFormat is false

See Also:

Format string syntax

checkNotNull

public static <T> T checkNotNull(T reference,
                                 String errorFormat,
                                 Object... args)

Ensures that reference is not null.

Parameters:

reference - an object reference that was passed as a parameter to the current method

errorFormat - format of error message to produce if the check fails

args - the arguments for errorFormat

Returns:

the non-null reference that was validated

Throws:

NullPointerException - if reference is null

See Also:

Format string syntax