Preconditions (JGoodies Common 1.8 API)
Date: 2015-01-03

com.jgoodies.common.base

## Class Preconditions

- java.lang.Object
- - com.jgoodies.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

    Methods
    Modifier and Type | Method and 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 Detail

    - #### 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

Copyright © 2009-2014 JGoodies Software GmbH. All Rights Reserved.