Package 

Class Preconditions

  • 
public final class Preconditions

    Simple static methods to be called at the start of your own methods to verify correct arguments and state. This allows constructs such as 

        if (count <= 0) {
      throw new IllegalArgumentException("must be positive: " + count);
    }

    to be replaced with the more compact 

    checkArgument(count > 0, "must be positive: %s", count);

    Note that the sense of the expression is inverted; with {@code Preconditions} you declare what you expect to be true, just as you do with an {@code assert} or a JUnit {@code assertTrue} call.

    Warning: only the {@code "%s"} specifier is recognized as a placeholder in these messages, not the full range of specifiers.

    Take care not to confuse precondition checking with other similar types of checks! Precondition exceptions -- including those provided here, but also IndexOutOfBoundsException, java.util.NoSuchElementException, and others -- are used to signal that the calling method has made an error. This tells the caller that it should not have invoked the method when it did, with the arguments it did, or perhaps ever. Postcondition or other invariant failures should not throw these types of exceptions.

    See the Guava User Guide on using {@code Preconditions}.

    • Method Summary

      Modifier and Type Method Description
      static void checkArgument(boolean expression) Ensures the truth of an expression involving one or more parameters to thecalling method.
      static void checkArgument(boolean expression, @Nullable() Object errorMessage) Ensures the truth of an expression involving one or more parameters to thecalling method.
      static void checkArgument(boolean expression, @Nullable() String errorMessageTemplate, @Nullable() Array<Object> errorMessageArgs) Ensures the truth of an expression involving one or more parameters to thecalling method.
      static void checkState(boolean expression) Ensures the truth of an expression involving the state of the callinginstance, but not involving any parameters to the calling method.
      static void checkState(boolean expression, @Nullable() Object errorMessage) Ensures the truth of an expression involving the state of the callinginstance, but not involving any parameters to the calling method.
      static void checkState(boolean expression, @Nullable() String errorMessageTemplate, @Nullable() Array<Object> errorMessageArgs) Ensures the truth of an expression involving the state of the callinginstance, but not involving any parameters to the calling method.
      static <T> T checkNotNull(T reference) Ensures that an object reference passed as a parameter to the callingmethod is not null.
      static <T> T checkNotNull(T reference, @Nullable() Object errorMessage) Ensures that an object reference passed as a parameter to the callingmethod is not null.
      static <T> T checkNotNull(T reference, @Nullable() String errorMessageTemplate, @Nullable() Array<Object> errorMessageArgs) Ensures that an object reference passed as a parameter to the callingmethod is not null.
      static int checkElementIndex(int index, int size) Ensures that {@code index} specifies a valid element in an array,list or string of size {@code size}.
      static int checkElementIndex(int index, int size, @Nullable() String desc) Ensures that {@code index} specifies a valid element in an array,list or string of size {@code size}.
      static int checkPositionIndex(int index, int size) Ensures that {@code index} specifies a valid position in an array,list or string of size {@code size}.
      static int checkPositionIndex(int index, int size, @Nullable() String desc) Ensures that {@code index} specifies a valid position in an array,list or string of size {@code size}.
      static void checkPositionIndexes(int start, int end, int size) Ensures that {@code start} and {@code end} specify a valid positionsin an array, list or string of size {@code size}, and are in order.

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • checkArgument

         static void checkArgument(boolean expression)

        Ensures the truth of an expression involving one or more parameters to thecalling method.

        Parameters:
        expression - a boolean expression

      • checkArgument

         static void checkArgument(boolean expression, @Nullable() Object errorMessage)

        Ensures the truth of an expression involving one or more parameters to thecalling method.

        Parameters:
        expression - a boolean expression
        errorMessage - the exception message to use if the check fails; willbe converted to a string using valueOf

      • checkArgument

         static void checkArgument(boolean expression, @Nullable() String errorMessageTemplate, @Nullable() Array<Object> errorMessageArgs)

        Ensures the truth of an expression involving one or more parameters to thecalling method.

        Parameters:
        expression - a boolean expression
        errorMessageTemplate - a template for the exception message should thecheck fail.
        errorMessageArgs - the arguments to be substituted into the messagetemplate.

      • checkState

         static void checkState(boolean expression)

        Ensures the truth of an expression involving the state of the callinginstance, but not involving any parameters to the calling method.

        Parameters:
        expression - a boolean expression

      • checkState

         static void checkState(boolean expression, @Nullable() Object errorMessage)

        Ensures the truth of an expression involving the state of the callinginstance, but not involving any parameters to the calling method.

        Parameters:
        expression - a boolean expression
        errorMessage - the exception message to use if the check fails; willbe converted to a string using valueOf

      • checkState

         static void checkState(boolean expression, @Nullable() String errorMessageTemplate, @Nullable() Array<Object> errorMessageArgs)

        Ensures the truth of an expression involving the state of the callinginstance, but not involving any parameters to the calling method.

        Parameters:
        expression - a boolean expression
        errorMessageTemplate - a template for the exception message should thecheck fail.
        errorMessageArgs - the arguments to be substituted into the messagetemplate.

      • checkNotNull

         static <T> T checkNotNull(T reference)

        Ensures that an object reference passed as a parameter to the callingmethod is not null.

        Parameters:
        reference - an object reference

      • checkNotNull

         static <T> T checkNotNull(T reference, @Nullable() Object errorMessage)

        Ensures that an object reference passed as a parameter to the callingmethod is not null.

        Parameters:
        reference - an object reference
        errorMessage - the exception message to use if the check fails; willbe converted to a string using valueOf

      • checkNotNull

         static <T> T checkNotNull(T reference, @Nullable() String errorMessageTemplate, @Nullable() Array<Object> errorMessageArgs)

        Ensures that an object reference passed as a parameter to the callingmethod is not null.

        Parameters:
        reference - an object reference
        errorMessageTemplate - a template for the exception message should thecheck fail.
        errorMessageArgs - the arguments to be substituted into the messagetemplate.

      • checkElementIndex

         static int checkElementIndex(int index, int size)

        Ensures that {@code index} specifies a valid element in an array,list or string of size {@code size}. An element index may range from zero,inclusive, to {@code size}, exclusive.

        Parameters:
        index - a user-supplied index identifying an element of an array, listor string
        size - the size of that array, list or string

      • checkElementIndex

         static int checkElementIndex(int index, int size, @Nullable() String desc)

        Ensures that {@code index} specifies a valid element in an array,list or string of size {@code size}. An element index may range from zero,inclusive, to {@code size}, exclusive.

        Parameters:
        index - a user-supplied index identifying an element of an array, listor string
        size - the size of that array, list or string
        desc - the text to use to describe this index in an error message

      • checkPositionIndex

         static int checkPositionIndex(int index, int size)

        Ensures that {@code index} specifies a valid position in an array,list or string of size {@code size}. A position index may range from zeroto {@code size}, inclusive.

        Parameters:
        index - a user-supplied index identifying a position in an array, listor string
        size - the size of that array, list or string

      • checkPositionIndex

         static int checkPositionIndex(int index, int size, @Nullable() String desc)

        Ensures that {@code index} specifies a valid position in an array,list or string of size {@code size}. A position index may range from zeroto {@code size}, inclusive.

        Parameters:
        index - a user-supplied index identifying a position in an array, listor string
        size - the size of that array, list or string
        desc - the text to use to describe this index in an error message

      • checkPositionIndexes

         static void checkPositionIndexes(int start, int end, int size)

        Ensures that {@code start} and {@code end} specify a valid positionsin an array, list or string of size {@code size}, and are in order. Aposition index may range from zero to {@code size}, inclusive.

        Parameters:
        start - a user-supplied index identifying a starting position in anarray, list or string
        end - a user-supplied index identifying a ending position in an array,list or string
        size - the size of that array, list or string