Package com.privatejgoodies.common.base

# Class Preconditions

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

public final class Preconditions extends Object
Reduces the code necessary to check preconditions on method state and parameters.

Author:
  Karsten Lentzsch

## Method Summary

Modifier and Type
Method
Description
`static void`
`checkArgument(boolean expression, String message)`
Checks the truth of the given expression and throws a customized `IllegalArgumentException` if it is false.
`static void`
`checkArgument(boolean expression, String messageFormat, Object... messageArgs)`
Checks the truth of the given expression and throws a customized `IllegalArgumentException` if it is false.
`static String`
`checkNotBlank(String str, String message)`
Checks that the given string is not blank and throws a customized `NullPointerException` if it is `null`, and a customized `IllegalArgumentException` if it is empty or whitespace.
`static String`
`checkNotBlank(String str, String messageFormat, Object... messageArgs)`
Checks that the given string is not blank and throws a customized `NullPointerException` if it is `null`, and a customized `IllegalArgumentException` if it is empty or whitespace.
`static <T> T`
`checkNotNull(T reference, String message)`
Checks that the given object reference is not `null` and throws a customized `NullPointerException` if it is.
`static <T> T`
`checkNotNull(T reference, String messageFormat, Object... messageArgs)`
Checks that the given object reference is not `null` and throws a customized `NullPointerException` if it is.
`static void`
`checkState(boolean expression, String message)`
Checks the truth of the given expression and throws a customized `IllegalStateException` if it is false.
`static void`
`checkState(boolean expression, String messageFormat, Object... messageArgs)`
Checks the truth of the given expression and throws a customized `IllegalStateException` if it is false.

### Methods inherited from class java.lang.Object

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

## Method Details

### checkArgument

public static void checkArgument(boolean expression, String message)
Checks the truth of the given expression and throws a customized `IllegalArgumentException` if it is false. Intended for doing parameter validation in methods and constructors, e.g.:

>      public void foo(int count) {
>         Preconditions.checkArgument(count > 0, "count must be positive.");
>      }

Parameters:
  `expression` - the precondition to check involving one ore more parameters to the calling method or constructor
  `message` - the detail message to be used in the event that an exception is thrown
Throws:
  `IllegalArgumentException` - if `expression` is false

### checkArgument

public static void checkArgument(boolean expression, String messageFormat, Object... messageArgs)
Checks the truth of the given expression and throws a customized `IllegalArgumentException` if it is false. Intended for doing parameter validation in methods and constructors, e.g.:

>      public void foo(int count) {
>         Preconditions.checkArgument(count > 0, "count must be positive: %s.", count);
>      }

Parameters:
  `expression` - the precondition to check involving one ore more parameters to the calling method or constructor
  `messageFormat` - a `format` string for the detail message to be used in the event that an exception is thrown.
  `messageArgs` - the arguments referenced by the format specifiers in the `messageFormat`
Throws:
  `IllegalArgumentException` - if `expression` is false

### checkNotNull

public static <T> T checkNotNull(T reference, String message)
Checks that the given object reference is not `null` and throws a customized `NullPointerException` if it is. Intended for doing parameter validation in methods and constructors, e.g.:

>      public void foo(Bar bar, Baz baz) {
>           this.bar = Preconditions.checkNotNull(bar, "bar must not be null.");
>           Preconditions.checkNotBull(baz, "baz must not be null.");
>      }

Type Parameters:
  `T` - the type of the reference
Parameters:
  `reference` - the object reference to check for being `null`
  `message` - the detail message to be used in the event that an exception is thrown
Returns:
  `reference` if not `null`
Throws:
  `NullPointerException` - if `reference` is `null`

### checkNotNull

public static <T> T checkNotNull(T reference, String messageFormat, Object... messageArgs)
Checks that the given object reference is not `null` and throws a customized `NullPointerException` if it is. Intended for doing parameter validation in methods and constructors, e.g.:

>      public void foo(Bar bar, Baz baz) {
>           this.bar = Preconditions.checkNotNull(bar, "bar must not be null.");
>           Preconditions.checkNotBull(baz, "The %s must not be null.", "baz");
>      }

Type Parameters:
  `T` - the type of the reference
Parameters:
  `reference` - the object reference to check for being `null`
  `messageFormat` - a `format` string for the detail message to be used in the event that an exception is thrown.
  `messageArgs` - the arguments referenced by the format specifiers in the `messageFormat`
Returns:
  `reference` if not `null`
Throws:
  `NullPointerException` - if `reference` is `null`

### checkState

public static void checkState(boolean expression, String message)
Checks the truth of the given expression and throws a customized `IllegalStateException` if it is false. Intended for doing validation in methods involving the state of the calling instance, but not involving parameters of the calling method, e.g.:

>      public void unlock() {
>         Preconditions.checkState(locked, "Must be locked to be unlocked.");
>      }

Parameters:
  `expression` - the precondition to check involving the state of the calling instance
  `message` - the detail message to be used in the event that an exception is thrown
Throws:
  `IllegalStateException` - if `expression` is false

### checkState

public static void checkState(boolean expression, String messageFormat, Object... messageArgs)
Checks the truth of the given expression and throws a customized `IllegalStateException` if it is false. Intended for doing validation in methods involving the state of the calling instance, but not involving parameters of the calling method, e.g.:

>      public void unlock() {
>         Preconditions.checkState(locked,
>             "Must be locked to be unlocked. Most recent lock: %s",
>             mostRecentLock);
>      }

Parameters:
  `expression` - the precondition to check involving the state of the calling instance
  `messageFormat` - a `format` string for the detail message to be used in the event that an exception is thrown.
  `messageArgs` - the arguments referenced by the format specifiers in the `messageFormat`
Throws:
  `IllegalStateException` - if `expression` is false

### checkNotBlank

public static String checkNotBlank(String str, String message)
Checks that the given string is not blank and throws a customized `NullPointerException` if it is `null`, and a customized `IllegalArgumentException` if it is empty or whitespace. Intended for doing parameter validation in methods and constructors, e.g.:

>      public void foo(String text) {
>           checkNotBlank(text, "The text must not be null, empty or whitespace.");
>      }

Parameters:
  `str` - the string to check for being blank
  `message` - the detail message to be used in the event that an exception is thrown
Returns:
  `str` if not `null`
Throws:
  `NullPointerException` - if `str` is `null`
  `IllegalArgumentException` - if `str` is empty or whitespace

### checkNotBlank

public static String checkNotBlank(String str, String messageFormat, Object... messageArgs)
Checks that the given string is not blank and throws a customized `NullPointerException` if it is `null`, and a customized `IllegalArgumentException` if it is empty or whitespace. Intended for doing parameter validation in methods and constructors, e.g.:

>      public void foo(String text, String id) {
>           checkNotBlank(
>               text,
>               "The text for %s must not be null, empty or whitespace.",
>               id);
>      }

Parameters:
  `str` - the string to check for being blank
  `messageFormat` - a `format` string for the detail message to be used in the event that an exception is thrown.
  `messageArgs` - the arguments referenced by the format specifiers in the `messageFormat`
Returns:
  `str` if not `null`
Throws:
  `NullPointerException` - if `str` is `null`
  `IllegalArgumentException` - if `str` is empty or whitespace