java/src/main/com/google/appengine/api/search/checkers/Preconditions.java

   1 /*
   2  * Copyright (C) 2007 Google Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 package com.google.appengine.api.search.checkers;
  18
  19 /**
  20  * Simple static methods to be called at the start of your own methods to verify
  21  * correct arguments and state. This allows constructs such as
  22  * <pre>{@code
  23  *     if (count <= 0) {
  24  *       throw new IllegalArgumentException("must be positive: " + count);
  25  *     }}</pre>
  26  *
  27  * to be replaced with the more compact
  28  * <pre>
  29  *     {@code checkArgument(count > 0, "must be positive: %s", count);}</pre>
  30  *
  31  * <p> Note that the sense of the expression is inverted; with {@code
  32  * Preconditions} you declare what you expect to be <i>true</i>, just as you
  33  * do with an
  34  * <a href="http://java.sun.com/j2se/1.5.0/docs/guide/language/assert.html">
  35  * {@code assert}</a> or a JUnit {@code assertTrue} call.
  36  *
  37  */
  38 public final class Preconditions {
  39   private Preconditions() {}
  40
  41   /**
  42    * Ensures the truth of an expression involving one or more parameters to the
  43    * calling method.
  44    *
  45    * @param expression a boolean expression
  46    * @param errorMessage the exception message to use if the check fails; will
  47    *     be converted to a string using {@link String#valueOf(Object)} if
  48    *     not null (a null will not be converted).
  49    * @throws IllegalArgumentException if {@code expression} is false
  50    */
  51   public static void checkArgument(
  52       boolean expression, Object errorMessage) {
  53     if (!expression) {
  54       throw new IllegalArgumentException(
  55           errorMessage != null ? String.valueOf(errorMessage) : null);
  56     }
  57   }
  58
  59   /**
  60    * Ensures the truth of an expression involving one or more parameters to the
  61    * calling method.
  62    *
  63    * @param expression a boolean expression
  64    * @param errorMessageTemplate a template for the exception message should the
  65    *     check fail. The message is formed using {@link String#format(String, Object...)}.
  66    *     if not null (a null will not be converted).
  67    * @param errorMessageArgs the arguments to be substituted into the message
  68    *     template.
  69    * @throws IllegalArgumentException if {@code expression} is false
  70    */
  71   public static void checkArgument(boolean expression, String errorMessageTemplate, Object... errorMessageArgs) {
  72     if (!expression) {
  73       throw new IllegalArgumentException(
  74           errorMessageTemplate != null
  75           ? String.format(errorMessageTemplate, errorMessageArgs) : null);
  76     }
  77   }
  78
  79   /**
  80    * Ensures that an object reference passed as a parameter to the calling
  81    * method is not null.
  82    *
  83    * @param reference an object reference
  84    * @param errorMessage the exception message to use if the check fails; will
  85    *     be converted to a string using {@link String#valueOf(Object)}
  86    * @return the non-null reference that was validated
  87    * @throws NullPointerException if {@code reference} is null
  88    */
  89   public static <T> T checkNotNull(T reference, Object errorMessage) {
  90     if (reference == null) {
  91       throw new NullPointerException(
  92           errorMessage != null ? String.valueOf(errorMessage) : null);
  93     }
  94     return reference;
  95   }
  96
  97   /**
  98    * Ensures the truth of an expression involving the state of the calling instance.
  99    *
 100    * @param expression a boolean expression
 101    * @param errorMessageTemplate a template for the exception message should the
 102    *     check fail. The message is formed using {@link String#format(String, Object...)}.
 103    *     if not null (a null will not be converted).
 104    * @param errorMessageArgs the arguments to be substituted into the message template.
 105    * @throws IllegalStateException if {@code expression} is false
 106    */
 107   public static void checkState(boolean expression, String errorMessageTemplate, Object... errorMessageArgs) {
 108     if (!expression) {
 109       throw new IllegalStateException(
 110           errorMessageTemplate != null ? String.format(errorMessageTemplate, errorMessageArgs)
 111               : null);
 112     }
 113   }
 114
 115   /**
 116    * Ensures the truth of an expression involving the state of the calling instance.
 117    *
 118    * @param expression a boolean expression
 119    * @param errorMessage the exception message to use if the check fails; will
 120    *     be converted to a string using {@link String#valueOf(Object)} if
 121    *     not null (a null will not be converted).
 122    * @throws IllegalStateException if {@code expression} is false
 123    */
 124   public static void checkState(boolean expression, String errorMessage) {
 125     if (!expression) {
 126       throw new IllegalStateException(
 127           errorMessage != null ? String.valueOf(errorMessage) : null);
 128     }
 129   }
 130 }