Verify
Date: 2016-05-24

com.google.common.base

## Class Verify

- java.lang.Object
- - com.google.common.base.Verify

-     @Beta
      @GwtCompatible
      public final class Verify
      extends java.lang.Object

  Static convenience methods that serve the same purpose as Java language assertions, except that they are always enabled. These methods should be used instead of Java assertions whenever there is a chance the check may fail "in real life". Example:

         Bill bill = remoteService.getLastUnpaidBill();

         // In case bug 12345 happens again we'd rather just die
         Verify.verify(bill.status() == Status.UNPAID,
             "Unexpected bill status: %s", bill.status());

  ### Comparison to alternatives

  Note: In some cases the differences explained below can be subtle. When it's unclear which approach to use, don't worry too much about it; just pick something that seems reasonable and it will be fine.

  - If checking whether the caller has violated your method or constructor's contract (such as by passing an invalid argument), use the utilities of the `Preconditions` class instead.
  - If checking an impossible condition (which cannot happen unless your own class or its trusted dependencies is badly broken), this is what ordinary Java assertions are for. Note that assertions are not enabled by default; they are essentially considered "compiled comments."
  - An explicit `if/throw` (as illustrated below) is always acceptable; we still recommend using our `VerifyException` exception type. Throwing a plain `RuntimeException` is frowned upon.
  - Use of `Objects.requireNonNull(Object)` is generally discouraged, since `verifyNotNull(Object)` and `Preconditions.checkNotNull(Object)` perform the same function with more clarity.

  ### Warning about performance

  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 verification succeeds and the message ends up unneeded. Performance-sensitive verification checks should continue to use usual form:

         Bill bill = remoteService.getLastUnpaidBill();
         if (bill.status() != Status.UNPAID) {
           throw new VerifyException("Unexpected bill status: " + bill.status());
         }

  ### Only `%s` is supported

  As with `Preconditions` error message template strings, only the `"%s"` specifier is supported, not the full range of `Formatter` specifiers. However, note that if the number of arguments does not match the number of occurrences of `"%s"` in the format string, `Verify` will still behave as expected, and will still include all argument values in the error message; the message will simply not be formatted exactly as intended.

  ### More information

  See Conditional failures explained in the Guava User Guide for advice on when this class should be used.
  Since:
    17.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `verify(boolean expression)` Ensures that `expression` is `true`, throwing a `VerifyException` with no message otherwise.
    `static void` | `verify(boolean expression, java.lang.String errorMessageTemplate, java.lang.Object... errorMessageArgs)` Ensures that `expression` is `true`, throwing a `VerifyException` with a custom message otherwise.
    `static <T> T` | `verifyNotNull(T reference)` Ensures that `reference` is non-null, throwing a `VerifyException` with a default message otherwise.
    `static <T> T` | `verifyNotNull(T reference, java.lang.String errorMessageTemplate, java.lang.Object... errorMessageArgs)` Ensures that `reference` is non-null, throwing a `VerifyException` with a custom message otherwise.

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

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

- - ### Method Detail

    - #### verify

          public static void verify(boolean expression)

      Ensures that `expression` is `true`, throwing a `VerifyException` with no message otherwise.
      Throws:
        `VerifyException` - if `expression` is `false`

    - #### verify

          public static void verify(boolean expression,
                    @Nullable
                    java.lang.String errorMessageTemplate,
                    @Nullable
                    java.lang.Object... errorMessageArgs)

      Ensures that `expression` is `true`, throwing a `VerifyException` with a custom message otherwise.
      Parameters:
        `expression` - a boolean expression
        `errorMessageTemplate` - a template for the exception message should the check fail. The message is formed by replacing each `%s` placeholder in the template with an argument. These are matched by position - the first `%s` gets `errorMessageArgs[0]`, etc. Unmatched arguments will be appended to the formatted message in square braces. Unmatched placeholders will be left as-is.
        `errorMessageArgs` - the arguments to be substituted into the message template. Arguments are converted to strings using `String.valueOf(Object)`.
      Throws:
        `VerifyException` - if `expression` is `false`

    - #### verifyNotNull

          public static <T> T verifyNotNull(@Nullable
                            T reference)

      Ensures that `reference` is non-null, throwing a `VerifyException` with a default message otherwise.
      Returns:
        `reference`, guaranteed to be non-null, for convenience
      Throws:
        `VerifyException` - if `reference` is `null`

    - #### verifyNotNull

          public static <T> T verifyNotNull(@Nullable
                            T reference,
                            @Nullable
                            java.lang.String errorMessageTemplate,
                            @Nullable
                            java.lang.Object... errorMessageArgs)

      Ensures that `reference` is non-null, throwing a `VerifyException` with a custom message otherwise.
      Parameters:
        `errorMessageTemplate` - a template for the exception message should the check fail. The message is formed by replacing each `%s` placeholder in the template with an argument. These are matched by position - the first `%s` gets `errorMessageArgs[0]`, etc. Unmatched arguments will be appended to the formatted message in square braces. Unmatched placeholders will be left as-is.
        `errorMessageArgs` - the arguments to be substituted into the message template. Arguments are converted to strings using `String.valueOf(Object)`.
      Returns:
        `reference`, guaranteed to be non-null, for convenience
      Throws:
        `VerifyException` - if `reference` is `null`