View Javadoc
1   /**
2    * Copyright 2010-2015 The Kuali Foundation
3    *
4    * Licensed under the Educational Community 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.opensource.org/licenses/ecl2.php
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  package org.kuali.common.jute.base;
17  
18  import static com.google.common.base.Preconditions.checkArgument;
19  import static org.apache.commons.lang3.StringUtils.isNotBlank;
20  import static org.apache.commons.lang3.StringUtils.isNotEmpty;
21  
22  import java.io.File;
23  
24  import com.google.common.base.Optional;
25  import com.google.common.base.Preconditions;
26  import com.google.common.collect.Iterables;
27  
28  /**
29   * Strongly mimic's Guava's {@code Preconditions} class with a sensible default error message for common situations
30   *
31   * <pre>
32   * {@code Guava:}
33   * checkArgument(StringUtils.isNotBlank(foo), &quot;'foo' cannot be blank&quot;);
34   * this.foo = foo;
35   *
36   * {@code Kuali:}
37   * this.foo = checkNotBlank(foo, &quot;foo&quot;);
38   * </pre>
39   */
40  public class Precondition {
41  
42      private static final String NOT_NULL_MSG = "'%s' cannot be null";
43      private static final String EXISTS_MSG = "[%s] does not exist";
44      private static final String IS_DIR_MSG = "[%s] is not an existing directory";
45      private static final String IS_FILE_MSG = "[%s] is not an existing file";
46      private static final String NOT_BLANK_MSG = "'%s' cannot be blank";
47      private static final String NOT_EMPTY_MSG = "'%s' cannot be the empty string";
48      private static final String MIN_MSG = "%s not allowed. '%s' must be greater than or equal to %s";
49      private static final String MAX_MSG = "%s not allowed. '%s' must be less than or equal to %s";
50      private static final String EQUALS_MSG = "[%s] not allowed. '%s' must be equal to [%s]";
51      private static final String NOT_EQUALS_MSG = "[%s] not allowed. '%s' must not be equal to [%s]";
52      private static final String ARG_NAME = "argName";
53  
54      /**
55       * Ensures that a File passed as an argument exists
56       *
57       * @param arg
58       *            a File passed as an argument
59       * @param argName
60       *            the name of the argument
61       *
62       * @return the non-null File that was validated
63       *
64       * @throws NullPointerException
65       *             If arg is null. The exception message contains the name of the argument that was null
66       * @throws IllegalArgumentException
67       *             If arg does not exist or argName is blank
68       */
69      public static File checkExists(File arg, String argName) {
70          checkNotBlank(argName, ARG_NAME);
71          checkNotNull(arg, argName);
72          checkArgument(arg.exists(), EXISTS_MSG, arg);
73          return arg;
74      }
75  
76      /**
77       * Ensures that a File passed as an argument is an existing directory
78       *
79       * @param arg
80       *            a File passed as an argument
81       * @param argName
82       *            the name of the argument
83       *
84       * @return the non-null File that was validated
85       *
86       * @throws NullPointerException
87       *             If arg is null. The exception message contains the name of the argument that was null
88       * @throws IllegalArgumentException
89       *             If arg does not exist, is not a directory, or argName is blank
90       */
91      public static File checkIsDir(File arg, String argName) {
92          checkArgument(checkExists(arg, argName).isDirectory(), IS_DIR_MSG, arg);
93          return arg;
94      }
95  
96      /**
97       * Ensures that a File passed as an argument is a normal file
98       *
99       * @param arg
100      *            a File passed as an argument
101      * @param argName
102      *            the name of the argument
103      *
104      * @return the non-null File that was validated
105      *
106      * @throws NullPointerException
107      *             If arg is null. The exception message contains the name of the argument that was null
108      * @throws IllegalArgumentException
109      *             If arg does not exist, is not a normal file, or argName is blank
110      */
111     public static File checkIsFile(File arg, String argName) {
112         checkArgument(checkExists(arg, argName).isFile(), IS_FILE_MSG, arg);
113         return arg;
114     }
115 
116     /**
117      * Ensures that an object reference passed as an argument is not null
118      *
119      * @param arg
120      *            an object reference passed as an argument
121      * @param argName
122      *            the name of the argument
123      *
124      * @return the non-null object reference that was validated
125      *
126      * @throws NullPointerException
127      *             If arg is null. The exception message contains the name of the argument that was null
128      * @throws IllegalArgumentException
129      *             If argName is blank
130      */
131     public static <T> T checkNotNull(T arg, String argName) {
132         checkNotBlank(argName, ARG_NAME);
133         return Preconditions.checkNotNull(arg, NOT_NULL_MSG, argName);
134     }
135 
136     /**
137      * Ensures that a String passed as an argument is not whitespace, empty ("") or null
138      *
139      * @param arg
140      *            a String passed as an argument
141      * @param argName
142      *            the name of the argument
143      *
144      * @return the non-blank String that was validated
145      *
146      * @throws IllegalArgumentException
147      *             If arg is blank. The exception message contains the name of the argument that was blank
148      * @throws IllegalArgumentException
149      *             If argName is blank
150      */
151     public static String checkNotBlank(String arg, String argName) {
152         checkArgument(isNotBlank(argName), NOT_BLANK_MSG, ARG_NAME);
153         checkArgument(isNotBlank(arg), NOT_BLANK_MSG, argName);
154         return arg;
155     }
156 
157     /**
158      * Ensures that a String passed as an argument is not the empty string ("") or null
159      *
160      * @param arg
161      *            a String passed as an argument
162      * @param argName
163      *            the name of the argument
164      *
165      * @return the non-blank String that was validated
166      *
167      * @throws IllegalArgumentException
168      *             If arg is blank. The exception message contains the name of the argument that was blank
169      * @throws IllegalArgumentException
170      *             If argName is blank
171      */
172     public static String checkNotEmpty(String arg, String argName) {
173         checkArgument(isNotBlank(argName), NOT_BLANK_MSG, ARG_NAME);
174         checkArgument(isNotEmpty(arg), NOT_EMPTY_MSG, argName);
175         return arg;
176     }
177 
178     /**
179      * Ensures that an {@code Optional<String>} passed as an argument does not contain a string that is whitespace or empty ("").
180      *
181      * @param arg
182      *            an {@code Optional<String>} passed as an argument
183      * @param argName
184      *            the name of the argument
185      *
186      * @return the non-blank {@code Optional<String>} that was validated
187      *
188      * @throws IllegalArgumentException
189      *             If arg is blank. The exception message contains the name of the argument that was blank
190      * @throws IllegalArgumentException
191      *             If argName is blank
192      */
193     public static Optional<String> checkNotBlank(Optional<String> arg, String argName) {
194         if (arg.isPresent()) {
195             checkNotBlank(arg.get(), argName);
196         }
197         return arg;
198     }
199 
200     /**
201      * Ensures that an {@code Optional<String>} passed as an argument is not the empty string ("").
202      *
203      * @param arg
204      *            an {@code Optional<String>} passed as an argument
205      * @param argName
206      *            the name of the argument
207      *
208      * @return the non-empty string {@code Optional<String>} that was validated
209      *
210      * @throws IllegalArgumentException
211      *             If arg is blank. The exception message contains the name of the argument that was blank
212      * @throws IllegalArgumentException
213      *             If argName is blank
214      */
215     public static Optional<String> checkNotEmpty(Optional<String> arg, String argName) {
216         if (arg.isPresent()) {
217             checkArgument(isNotEmpty(arg.get()), NOT_EMPTY_MSG, argName);
218         }
219         return arg;
220     }
221 
222     /**
223      * If arg.isPresent(), check that the Integer it contains is greater than or equal to min
224      */
225     public static Optional<Integer> checkMin(Optional<Integer> arg, int min, String argName) {
226         if (arg.isPresent()) {
227             checkMin(arg.get(), min, argName);
228         }
229         return arg;
230     }
231 
232     /**
233      * If arg.isPresent(), check that the Long it contains is greater than or equal to min
234      */
235     public static Optional<Long> checkMin(Optional<Long> arg, long min, String argName) {
236         if (arg.isPresent()) {
237             checkMin(arg.get(), min, argName);
238         }
239         return arg;
240     }
241 
242     /**
243      * Check that arg is less than or equal to max
244      */
245     public static int checkMax(int arg, int max, String argName) {
246         checkNotBlank(argName, ARG_NAME);
247         checkArgument(arg <= max, MAX_MSG, arg, argName, max);
248         return arg;
249     }
250 
251     /**
252      * Check that arg is less than or equal to max
253      */
254     public static long checkMax(long arg, long max, String argName) {
255         checkNotBlank(argName, ARG_NAME);
256         checkArgument(arg <= max, MAX_MSG, arg, argName, max);
257         return arg;
258     }
259 
260     public static int checkRange(int arg, int min, int max, String argName) {
261         return checkMin(checkMax(arg, max, argName), min, argName);
262     }
263 
264     /**
265      * Check that arg is greater than or equal to min.
266      */
267     public static int checkMin(int arg, int min, String argName) {
268         checkNotBlank(argName, ARG_NAME);
269         checkArgument(arg >= min, MIN_MSG, arg, argName, min);
270         return arg;
271     }
272 
273     /**
274      * Check that arg is greater than or equal to min.
275      */
276     public static long checkMin(long arg, long min, String argName) {
277         checkNotBlank(argName, ARG_NAME);
278         checkArgument(arg >= min, MIN_MSG, arg, argName, min);
279         return arg;
280     }
281 
282     public static <T> T checkNotEquals(T arg, T illegal, String argName) {
283         checkNotNull(arg, checkNotBlank(argName, ARG_NAME));
284         checkNotNull(illegal, "illegal");
285         checkArgument(!arg.equals(illegal), NOT_EQUALS_MSG, argName, arg, illegal);
286         return arg;
287     }
288 
289     public static <T> T checkEquals(T arg, T expected, String argName) {
290         checkNotNull(arg, checkNotBlank(argName, ARG_NAME));
291         checkNotNull(expected, "expected");
292         checkArgument(arg.equals(expected), EQUALS_MSG, argName, arg, expected);
293         return arg;
294     }
295 
296     public static long checkEquals(long arg, long expected, String argName) {
297         checkNotBlank(argName, ARG_NAME);
298         checkArgument(arg == expected, EQUALS_MSG, argName, arg, expected);
299         return arg;
300     }
301 
302     public static int checkEquals(int arg, int expected, String argName) {
303         checkNotBlank(argName, ARG_NAME);
304         checkArgument(arg == expected, EQUALS_MSG, argName, arg, expected);
305         return arg;
306     }
307 
308     public static void checkTruths(int expected, boolean... expressions) {
309         checkMin(expected, 0, "expected");
310         checkArgument(expressions.length > 0, "must supply at least 1 expression");
311         int actual = 0;
312         for (boolean expression : expressions) {
313             actual = expression ? (actual + 1) : actual;
314         }
315         checkArgument(expected == actual, "expected %s of %s expression(s) to be true, but %s were true instead", expected, expressions.length, actual);
316     }
317 
318     public static <I extends Iterable<T>, T> I checkSize(I iterable, int expected) {
319         int actual = Iterables.size(iterable);
320         checkArgument(expected == actual, "expected exactly %s element(s) but there were %s instead", expected, actual);
321         return iterable;
322     }
323 
324 }