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), "'foo' cannot be blank");
34 * this.foo = foo;
35 *
36 * {@code Kuali:}
37 * this.foo = checkNotBlank(foo, "foo");
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 }