2 * Copyright (C) 2007 Google Inc.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 package com
.google
.appengine
.api
.search
.checkers
;
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
24 * throw new IllegalArgumentException("must be positive: " + count);
27 * to be replaced with the more compact
29 * checkArgument(count > 0, "must be positive: %s", count);</pre>
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
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.
38 public final class Preconditions
{
39 private Preconditions() {}
42 * Ensures the truth of an expression involving one or more parameters to the
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
51 public static void checkArgument(
52 boolean expression
, Object errorMessage
) {
54 throw new IllegalArgumentException(
55 errorMessage
!= null ? String
.valueOf(errorMessage
) : null);
60 * Ensures the truth of an expression involving one or more parameters to the
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
69 * @throws IllegalArgumentException if {@code expression} is false
71 public static void checkArgument(boolean expression
, String errorMessageTemplate
, Object
... errorMessageArgs
) {
73 throw new IllegalArgumentException(
74 errorMessageTemplate
!= null
75 ? String
.format(errorMessageTemplate
, errorMessageArgs
) : null);
80 * Ensures that an object reference passed as a parameter to the calling
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
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);
98 * Ensures the truth of an expression involving the state of the calling instance.
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
107 public static void checkState(boolean expression
, String errorMessageTemplate
, Object
... errorMessageArgs
) {
109 throw new IllegalStateException(
110 errorMessageTemplate
!= null ? String
.format(errorMessageTemplate
, errorMessageArgs
)
116 * Ensures the truth of an expression involving the state of the calling instance.
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
124 public static void checkState(boolean expression
, String errorMessage
) {
126 throw new IllegalStateException(
127 errorMessage
!= null ? String
.valueOf(errorMessage
) : null);