Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  /*
   * Copyright (C) 2007 The Guava Authors
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   * http://www.apache.org/licenses/LICENSE-2.0
   *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 
 package com.google.common.base;
 
 
 
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 Preconditions you declare what you expect to be true, just as you do with an assert or a JUnit assertTrue call.

Warning: only the "%s" specifier is recognized as a placeholder in these messages, not the full range of java.lang.String.format(java.lang.String,java.lang.Object[]) specifiers.

Take care not to confuse precondition checking with other similar types of checks! Precondition exceptions -- including those provided here, but also java.lang.IndexOutOfBoundsException, java.util.NoSuchElementException, java.lang.UnsupportedOperationException 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 Preconditions.

Author(s):
Kevin Bourrillion
Since:
2.0 (imported from Google Collections Library)
 
 public final class Preconditions {
   private Preconditions() {}

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

Parameters:
expression a boolean expression
Throws:
java.lang.IllegalArgumentException if expression is false
 
   public static void checkArgument(boolean expression) {
     if (!expression) {
       throw new IllegalArgumentException();
     }
   }

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

Parameters:
expression a boolean expression
errorMessage the exception message to use if the check fails; will be converted to a string using java.lang.String.valueOf(java.lang.Object)
Throws:
java.lang.IllegalArgumentException if expression is false
 
   public static void checkArgument(
       boolean expression, @Nullable Object errorMessage) {
     if (!expression) {
       throw new IllegalArgumentException(String.valueOf(errorMessage));
     }
   }

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

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 java.lang.String.valueOf(java.lang.Object).
Throws:
java.lang.IllegalArgumentException if expression is false
java.lang.NullPointerException if the check fails and either errorMessageTemplate or errorMessageArgs is null (don't let this happen)
  public static void checkArgument(boolean expression,
      @Nullable String errorMessageTemplate,
      @Nullable Object... errorMessageArgs) {
    if (!expression) {
      throw new IllegalArgumentException(
          format(errorMessageTemplateerrorMessageArgs));
    }
  }

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

Parameters:
expression a boolean expression
Throws:
java.lang.IllegalStateException if expression is false
  public static void checkState(boolean expression) {
    if (!expression) {
      throw new IllegalStateException();
    }
  }

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

Parameters:
expression a boolean expression
errorMessage the exception message to use if the check fails; will be converted to a string using java.lang.String.valueOf(java.lang.Object)
Throws:
java.lang.IllegalStateException if expression is false
  public static void checkState(
      boolean expression, @Nullable Object errorMessage) {
    if (!expression) {
      throw new IllegalStateException(String.valueOf(errorMessage));
    }
  }

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

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 java.lang.String.valueOf(java.lang.Object).
Throws:
java.lang.IllegalStateException if expression is false
java.lang.NullPointerException if the check fails and either errorMessageTemplate or errorMessageArgs is null (don't let this happen)
  public static void checkState(boolean expression,
      @Nullable String errorMessageTemplate,
      @Nullable Object... errorMessageArgs) {
    if (!expression) {
      throw new IllegalStateException(
          format(errorMessageTemplateerrorMessageArgs));
    }
  }

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

Parameters:
reference an object reference
Returns:
the non-null reference that was validated
Throws:
java.lang.NullPointerException if reference is null
  public static <T> T checkNotNull(T reference) {
    if (reference == null) {
      throw new NullPointerException();
    }
    return reference;
  }

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

Parameters:
reference an object reference
errorMessage the exception message to use if the check fails; will be converted to a string using java.lang.String.valueOf(java.lang.Object)
Returns:
the non-null reference that was validated
Throws:
java.lang.NullPointerException if reference is null
  public static <T> T checkNotNull(T reference, @Nullable Object errorMessage) {
    if (reference == null) {
      throw new NullPointerException(String.valueOf(errorMessage));
    }
    return reference;
  }

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

Parameters:
reference an object reference
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 java.lang.String.valueOf(java.lang.Object).
Returns:
the non-null reference that was validated
Throws:
java.lang.NullPointerException if reference is null
  public static <T> T checkNotNull(T reference,
      @Nullable String errorMessageTemplate,
      @Nullable Object... errorMessageArgs) {
    if (reference == null) {
      // If either of these parameters is null, the right thing happens anyway
      throw new NullPointerException(
          format(errorMessageTemplateerrorMessageArgs));
    }
    return reference;
  }
  /*
   * All recent hotspots (as of 2009) *really* like to have the natural code
   *
   * if (guardExpression) {
   *    throw new BadException(messageExpression);
   * }
   *
   * refactored so that messageExpression is moved to a separate
   * String-returning method.
   *
   * if (guardExpression) {
   *    throw new BadException(badMsg(...));
   * }
   *
   * The alternative natural refactorings into void or Exception-returning
   * methods are much slower.  This is a big deal - we're talking factors of
   * 2-8 in microbenchmarks, not just 10-20%.  (This is a hotspot optimizer
   * bug, which should be fixed, but that's a separate, big project).
   *
   * The coding pattern above is heavily used in java.util, e.g. in ArrayList.
   * There is a RangeCheckMicroBenchmark in the JDK that was used to test this.
   *
   * But the methods in this class want to throw different exceptions,
   * depending on the args, so it appears that this pattern is not directly
   * applicable.  But we can use the ridiculous, devious trick of throwing an
   * exception in the middle of the construction of another exception.
   * Hotspot is fine with that.
   */

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

Parameters:
index a user-supplied index identifying an element of an array, list or string
size the size of that array, list or string
Returns:
the value of index
Throws:
java.lang.IndexOutOfBoundsException if index is negative or is not less than size
java.lang.IllegalArgumentException if size is negative
  public static int checkElementIndex(int indexint size) {
    return checkElementIndex(indexsize"index");
  }

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

Parameters:
index a user-supplied index identifying an element of an array, list or string
size the size of that array, list or string
desc the text to use to describe this index in an error message
Returns:
the value of index
Throws:
java.lang.IndexOutOfBoundsException if index is negative or is not less than size
java.lang.IllegalArgumentException if size is negative
  public static int checkElementIndex(
      int indexint size, @Nullable String desc) {
    // Carefully optimized for execution by hotspot (explanatory comment above)
    if (index < 0 || index >= size) {
      throw new IndexOutOfBoundsException(badElementIndex(indexsizedesc));
    }
    return index;
  }
  private static String badElementIndex(int indexint sizeString desc) {
    if (index < 0) {
      return format("%s (%s) must not be negative"descindex);
    } else if (size < 0) {
      throw new IllegalArgumentException("negative size: " + size);
    } else { // index >= size
      return format("%s (%s) must be less than size (%s)"descindexsize);
    }
  }

  
Ensures that index specifies a valid position in an array, list or string of size size. A position index may range from zero to size, inclusive.

Parameters:
index a user-supplied index identifying a position in an array, list or string
size the size of that array, list or string
Returns:
the value of index
Throws:
java.lang.IndexOutOfBoundsException if index is negative or is greater than size
java.lang.IllegalArgumentException if size is negative
  public static int checkPositionIndex(int indexint size) {
    return checkPositionIndex(indexsize"index");
  }

  
Ensures that index specifies a valid position in an array, list or string of size size. A position index may range from zero to size, inclusive.

Parameters:
index a user-supplied index identifying a position in an array, list or string
size the size of that array, list or string
desc the text to use to describe this index in an error message
Returns:
the value of index
Throws:
java.lang.IndexOutOfBoundsException if index is negative or is greater than size
java.lang.IllegalArgumentException if size is negative
  public static int checkPositionIndex(
      int indexint size, @Nullable String desc) {
    // Carefully optimized for execution by hotspot (explanatory comment above)
    if (index < 0 || index > size) {
      throw new IndexOutOfBoundsException(badPositionIndex(indexsizedesc));
    }
    return index;
  }
  private static String badPositionIndex(int indexint sizeString desc) {
    if (index < 0) {
      return format("%s (%s) must not be negative"descindex);
    } else if (size < 0) {
      throw new IllegalArgumentException("negative size: " + size);
    } else { // index > size
      return format("%s (%s) must not be greater than size (%s)",
                    descindexsize);
    }
  }

  
Ensures that start and end specify a valid positions in an array, list or string of size size, and are in order. A position index may range from zero to size, inclusive.

Parameters:
start a user-supplied index identifying a starting position in an array, 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
Throws:
java.lang.IndexOutOfBoundsException if either index is negative or is greater than size, or if end is less than start
java.lang.IllegalArgumentException if size is negative
  public static void checkPositionIndexes(int startint endint size) {
    // Carefully optimized for execution by hotspot (explanatory comment above)
    if (start < 0 || end < start || end > size) {
      throw new IndexOutOfBoundsException(badPositionIndexes(startendsize));
    }
  }
  private static String badPositionIndexes(int startint endint size) {
    if (start < 0 || start > size) {
      return badPositionIndex(startsize"start index");
    }
    if (end < 0 || end > size) {
      return badPositionIndex(endsize"end index");
    }
    // end < start
    return format("end index (%s) must not be less than start index (%s)",
                  endstart);
  }

  
Substitutes each %s in template with an argument. These are matched by position - the first %s gets args[0], etc. If there are more arguments than placeholders, the unmatched arguments will be appended to the end of the formatted message in square braces.

Parameters:
template a non-null string containing 0 or more %s placeholders.
args the arguments to be substituted into the message template. Arguments are converted to strings using java.lang.String.valueOf(java.lang.Object). Arguments can be null.
  @VisibleForTesting static String format(String template,
      @Nullable Object... args) {
    template = String.valueOf(template); // null -> "null"
    // start substituting the arguments into the '%s' placeholders
    StringBuilder builder = new StringBuilder(
        template.length() + 16 * args.length);
    int templateStart = 0;
    int i = 0;
    while (i < args.length) {
      int placeholderStart = template.indexOf("%s"templateStart);
      if (placeholderStart == -1) {
        break;
      }
      builder.append(template.substring(templateStartplaceholderStart));
      builder.append(args[i++]);
      templateStart = placeholderStart + 2;
    }
    builder.append(template.substring(templateStart));
    // if we run out of placeholders, append the extra args in square braces
    if (i < args.length) {
      builder.append(" [");
      builder.append(args[i++]);
      while (i < args.length) {
        builder.append(", ");
        builder.append(args[i++]);
      }
      builder.append(']');
    }
    return builder.toString();
  }
New to GrepCode? Check out our FAQ X