1 /**
2 * Copyright 2010-2014 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.util.base;
17
18 import static com.google.common.base.Preconditions.checkArgument;
19 import static org.apache.commons.lang3.StringUtils.isNotBlank;
20
21 import java.io.File;
22
23 import com.google.common.base.Optional;
24 import com.google.common.base.Preconditions;
25
26 /**
27 * Strongly mimic's Guava's {@code Preconditions} class with a sensible default error message for common situations
28 *
29 * <pre>
30 * {@code Guava:}
31 * checkArgument(!StringUtils.isBlank(foo), "'foo' cannot be blank");
32 * this.foo = foo;
33 *
34 * {@code Kuali:}
35 * this.foo = checkNotBlank(foo, "foo");
36 * </pre>
37 */
38 public class Precondition {
39
40 private static final String NOT_NULL_MSG = "'%s' cannot be null";
41 private static final String EXISTS_MSG = "[%s] does not exist";
42 private static final String IS_DIR_MSG = "[%s] is not an existing directory";
43 private static final String IS_FILE_MSG = "[%s] is not an existing file";
44 private static final String NOT_BLANK_MSG = "'%s' cannot be blank";
45 private static final String MIN_MSG = "%s not allowed. '%s' must be greater than or equal to %s";
46 private static final String MAX_MSG = "%s not allowed. '%s' must be less than or equal to %s";
47 private static final String EQUALS_MSG = "[%s] not allowed. '%s' must be equal to [%s]";
48 private static final String ARG_NAME = "argName";
49
50 /**
51 * Ensures that a File passed as an argument exists
52 *
53 * @param arg
54 * a File passed as an argument
55 * @param argName
56 * the name of the argument
57 *
58 * @return the non-null File that was validated
59 *
60 * @throws NullPointerException
61 * If arg is null. The exception message contains the name of the argument that was null
62 * @throws IllegalArgumentException
63 * If arg does not exist or argName is blank
64 */
65 public static File checkExists(File arg, String argName) {
66 checkNotBlank(argName, ARG_NAME);
67 checkNotNull(arg, argName);
68 checkArgument(arg.exists(), EXISTS_MSG, arg);
69 return arg;
70 }
71
72 /**
73 * Ensures that a File passed as an argument is an existing directory
74 *
75 * @param arg
76 * a File passed as an argument
77 * @param argName
78 * the name of the argument
79 *
80 * @return the non-null File that was validated
81 *
82 * @throws NullPointerException
83 * If arg is null. The exception message contains the name of the argument that was null
84 * @throws IllegalArgumentException
85 * If arg does not exist, is not a directory, or argName is blank
86 */
87 public static File checkIsDir(File arg, String argName) {
88 checkArgument(checkExists(arg, argName).isDirectory(), IS_DIR_MSG, arg);
89 return arg;
90 }
91
92 /**
93 * Ensures that a File passed as an argument is a normal file
94 *
95 * @param arg
96 * a File passed as an argument
97 * @param argName
98 * the name of the argument
99 *
100 * @return the non-null File that was validated
101 *
102 * @throws NullPointerException
103 * If arg is null. The exception message contains the name of the argument that was null
104 * @throws IllegalArgumentException
105 * If arg does not exist, is not a normal file, or argName is blank
106 */
107 public static File checkIsFile(File arg, String argName) {
108 checkArgument(checkExists(arg, argName).isFile(), IS_FILE_MSG, arg);
109 return arg;
110 }
111
112 /**
113 * Ensures that an object reference passed as an argument is not null
114 *
115 * @param arg
116 * an object reference passed as an argument
117 * @param argName
118 * the name of the argument
119 *
120 * @return the non-null object reference that was validated
121 *
122 * @throws NullPointerException
123 * If arg is null. The exception message contains the name of the argument that was null
124 * @throws IllegalArgumentException
125 * If argName is blank
126 */
127 public static <T> T checkNotNull(T arg, String argName) {
128 return Preconditions.checkNotNull(arg, NOT_NULL_MSG, checkNotBlank(argName, ARG_NAME));
129 }
130
131 /**
132 * Ensures that a String passed as an argument is not whitespace, empty ("") or null
133 *
134 * @param arg
135 * a String passed as an argument
136 * @param argName
137 * the name of the argument
138 *
139 * @return the non-blank String that was validated
140 *
141 * @throws IllegalArgumentException
142 * If arg is blank. The exception message contains the name of the argument that was blank
143 * @throws IllegalArgumentException
144 * If argName is blank
145 */
146 public static String checkNotBlank(String arg, String argName) {
147 checkArgument(isNotBlank(argName), NOT_BLANK_MSG, ARG_NAME);
148 checkArgument(isNotBlank(arg), NOT_BLANK_MSG, argName);
149 return arg;
150 }
151
152 /**
153 * Ensures that an {@code Optional<String>} passed as an argument does not contain a string that is whitespace or empty ("").
154 *
155 * @param arg
156 * an {@code Optional<String>} passed as an argument
157 * @param argName
158 * the name of the argument
159 *
160 * @return the non-blank {@code Optional<String>} that was validated
161 *
162 * @throws IllegalArgumentException
163 * If arg is blank. The exception message contains the name of the argument that was blank
164 * @throws IllegalArgumentException
165 * If argName is blank
166 */
167 public static Optional<String> checkNotBlank(Optional<String> arg, String argName) {
168 if (arg.isPresent()) {
169 checkNotBlank(arg.get(), argName);
170 }
171 return arg;
172 }
173
174 /**
175 * If arg.isPresent(), check that the Integer it contains is greater than or equal to min
176 */
177 public static Optional<Integer> checkMin(Optional<Integer> arg, int min, String argName) {
178 if (arg.isPresent()) {
179 checkMin(arg.get(), min, argName);
180 }
181 return arg;
182 }
183
184 /**
185 * If arg.isPresent(), check that the Long it contains is greater than or equal to min
186 */
187 public static Optional<Long> checkMin(Optional<Long> arg, long min, String argName) {
188 if (arg.isPresent()) {
189 checkMin(arg.get(), min, argName);
190 }
191 return arg;
192 }
193
194 /**
195 * Check that arg is less than or equal to max
196 */
197 public static int checkMax(int arg, int max, String argName) {
198 checkNotBlank(argName, ARG_NAME);
199 checkArgument(arg <= max, MAX_MSG, arg, argName, max);
200 return arg;
201 }
202
203 /**
204 * Check that arg is less than or equal to max
205 */
206 public static long checkMax(long arg, long max, String argName) {
207 checkNotBlank(argName, ARG_NAME);
208 checkArgument(arg <= max, MAX_MSG, arg, argName, max);
209 return arg;
210 }
211
212 /**
213 * Check that arg is greater than or equal to min.
214 */
215 public static int checkMin(int arg, int min, String argName) {
216 checkNotBlank(argName, ARG_NAME);
217 checkArgument(arg >= min, MIN_MSG, arg, argName, min);
218 return arg;
219 }
220
221 /**
222 * Check that arg is greater than or equal to min.
223 */
224 public static long checkMin(long arg, long min, String argName) {
225 checkNotBlank(argName, ARG_NAME);
226 checkArgument(arg >= min, MIN_MSG, arg, argName, min);
227 return arg;
228 }
229
230 public static void checkEquals(Object arg, Object expected, String argName) {
231 checkNotNull(arg, checkNotBlank(argName, ARG_NAME));
232 checkNotNull(expected, "expected");
233 checkArgument(arg.equals(expected), EQUALS_MSG, argName, arg, expected);
234 }
235 }