001: /*
002: * Copyright 2004-2006 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.compass.core.util;
018:
019: import java.util.Collection;
020: import java.util.Map;
021:
022: /**
023: * Assert utility class that assists in validating arguments. Useful for
024: * identifying programmer errors early and obviously at runtime.
025: *
026: * <p>For example, if the contract of a public method states it does not allow null
027: * arguments, Assert can be used to validate that contract. Doing this clearly
028: * indicates a contract violation when it occurs and protects the class's
029: * invariants.
030: *
031: * <p>Typically used to validate method arguments rather than configuration
032: * properties, to check for cases that are usually programmer errors rather than
033: * configuration errors. In contrast to config initialization code, there is
034: * usally no point in falling back to defaults in such methods.
035: *
036: * <p>This class is similar to JUnit's assertion library. If an argument value is
037: * deemed invalid, an IllegalArgumentException is thrown. For example:
038: *
039: * <pre>
040: * Assert.notNull(clazz, "The class must not be null");
041: * Assert.isTrue(i > 0, "The value must be greater than zero");</pre>
042: *
043: * Mainly for internal use within the framework; consider Jakarta's Commons Lang
044: * >= 2.0 for a more comprehensive suite of assertion utilities.
045: *
046: * @author kimchy
047: */
048: public abstract class Assert {
049:
050: /**
051: * Assert a boolean expression, throwing <code>IllegalArgumentException</code>
052: * if the test result is <code>false</code>.
053: * <pre>
054: * Assert.isTrue(i > 0, "The value must be greater than zero");</pre>
055: * @param expression a boolean expression
056: * @param message the exception message to use if the assertion fails
057: * @throws IllegalArgumentException if expression is <code>false</code>
058: */
059: public static void isTrue(boolean expression, String message) {
060: if (!expression) {
061: throw new IllegalArgumentException(message);
062: }
063: }
064:
065: /**
066: * Assert a boolean expression, throwing <code>IllegalArgumentException</code>
067: * if the test result is <code>false</code>.
068: * <pre>
069: * Assert.isTrue(i > 0);</pre>
070: * @param expression a boolean expression
071: * @throws IllegalArgumentException if expression is <code>false</code>
072: */
073: public static void isTrue(boolean expression) {
074: isTrue(expression,
075: "[Assertion failed] - this expression must be true");
076: }
077:
078: /**
079: * Assert that an object is not null.
080: * <pre>
081: * Assert.notNull(clazz, "The class must not be null");</pre>
082: * @param object the object to check
083: * @param message the exception message to use if the assertion fails
084: * @throws IllegalArgumentException if the object is <code>null</code>
085: */
086: public static void notNull(Object object, String message) {
087: if (object == null) {
088: throw new IllegalArgumentException(message);
089: }
090: }
091:
092: /**
093: * Assert that an object is not null.
094: * <pre>
095: * Assert.notNull(clazz);</pre>
096: * @param object the object to check
097: * @throws IllegalArgumentException if the object is <code>null</code>
098: */
099: public static void notNull(Object object) {
100: notNull(object,
101: "[Assertion failed] - this argument is required; it cannot be null");
102: }
103:
104: /**
105: * Assert that a string is not empty; that is, it must not be <code>null</code> and not empty.
106: * <pre>
107: * Assert.hasLength(name, "Name must not be empty");</pre>
108: * @param text the string to check
109: * @param message the exception message to use if the assertion fails
110: * @see StringUtils#hasLength
111: */
112: public static void hasLength(String text, String message) {
113: if (!StringUtils.hasLength(text)) {
114: throw new IllegalArgumentException(message);
115: }
116: }
117:
118: /**
119: * Assert that a string is not empty; that is, it must not be <code>null</code> and not empty.
120: * <pre>
121: * Assert.hasLength(name);</pre>
122: * @param text the string to check
123: * @see StringUtils#hasLength
124: */
125: public static void hasLength(String text) {
126: hasLength(
127: text,
128: "[Assertion failed] - this String argument must have length; it cannot be <code>null</code> or empty");
129: }
130:
131: /**
132: * Assert that a string has valid text content; that is, it must not be <code>null</code>
133: * and must contain at least one non-whitespace character.
134: * <pre>
135: * Assert.hasText(name, "Name must not be empty");</pre>
136: * @param text the string to check
137: * @param message the exception message to use if the assertion fails
138: * @see StringUtils#hasText
139: */
140: public static void hasText(String text, String message) {
141: if (!StringUtils.hasText(text)) {
142: throw new IllegalArgumentException(message);
143: }
144: }
145:
146: /**
147: * Assert that a string has valid text content; that is, it must not be <code>null</code>
148: * and must contain at least one non-whitespace character.
149: * <pre>
150: * Assert.hasText(name, "Name must not be empty");</pre>
151: * @param text the string to check
152: * @see StringUtils#hasText
153: */
154: public static void hasText(String text) {
155: hasText(
156: text,
157: "[Assertion failed] - this String argument must have text; it cannot be <code>null</code>, empty, or blank");
158: }
159:
160: /**
161: * Assert that the given text does not contain the given substring.
162: * <pre>
163: * Assert.doesNotContain(name, "rod", "Name must not contain 'rod'");</pre>
164: * @param textToSearch the text to search
165: * @param substring the substring to find within the text
166: * @param message the exception message to use if the assertion fails
167: */
168: public static void doesNotContain(String textToSearch,
169: String substring, String message) {
170: if (textToSearch.indexOf(substring) != -1) {
171: throw new IllegalArgumentException(message);
172: }
173: }
174:
175: /**
176: * Assert that the given text does not contain the given substring.
177: * <pre>
178: * Assert.doesNotContain(name, "rod");</pre>
179: * @param textToSearch the text to search
180: * @param substring the substring to find within the text
181: */
182: public static void doesNotContain(String textToSearch,
183: String substring) {
184: doesNotContain(textToSearch, substring,
185: "[Assertion failed] - this String argument must not contain the substring ["
186: + substring + "]");
187: }
188:
189: /**
190: * Assert that an array has elements; that is, it must not be
191: * <code>null</code> and must have at least one element.
192: * <pre>
193: * Assert.notEmpty(array, "The array must have elements");</pre>
194: * @param array the array to check
195: * @param message the exception message to use if the assertion fails
196: * @throws IllegalArgumentException if the object array is <code>null</code> or has no elements
197: */
198: public static void notEmpty(Object[] array, String message) {
199: if (array == null || array.length == 0) {
200: throw new IllegalArgumentException(message);
201: }
202: }
203:
204: /**
205: * Assert that an array has elements; that is, it must not be
206: * <code>null</code> and must have at least one element.
207: * <pre>
208: * Assert.notEmpty(array);</pre>
209: * @param array the array to check
210: * @throws IllegalArgumentException if the object array is <code>null</code> or has no elements
211: */
212: public static void notEmpty(Object[] array) {
213: notEmpty(
214: array,
215: "[Assertion failed] - this array must not be empty: it must contain at least 1 element");
216: }
217:
218: /**
219: * Assert that a collection has elements; that is, it must not be
220: * <code>null</code> and must have at least one element.
221: * <pre>
222: * Assert.notEmpty(collection, "Collection must have elements");</pre>
223: * @param collection the collection to check
224: * @param message the exception message to use if the assertion fails
225: * @throws IllegalArgumentException if the collection is <code>null</code> or has no elements
226: */
227: public static void notEmpty(Collection collection, String message) {
228: if (collection == null || collection.isEmpty()) {
229: throw new IllegalArgumentException(message);
230: }
231: }
232:
233: /**
234: * Assert that a collection has elements; that is, it must not be
235: * <code>null</code> and must have at least one element.
236: * <pre>
237: * Assert.notEmpty(collection, "Collection must have elements");</pre>
238: * @param collection the collection to check
239: * @throws IllegalArgumentException if the collection is <code>null</code> or has no elements
240: */
241: public static void notEmpty(Collection collection) {
242: notEmpty(
243: collection,
244: "[Assertion failed] - this collection must not be empty: it must contain at least 1 element");
245: }
246:
247: /**
248: * Assert that a Map has entries; that is, it must not be <code>null</code>
249: * and must have at least one entry.
250: * <pre>
251: * Assert.notEmpty(map, "Map must have entries");</pre>
252: * @param map the map to check
253: * @param message the exception message to use if the assertion fails
254: * @throws IllegalArgumentException if the map is <code>null</code> or has no entries
255: */
256: public static void notEmpty(Map map, String message) {
257: if (map == null || map.isEmpty()) {
258: throw new IllegalArgumentException(message);
259: }
260: }
261:
262: /**
263: * Assert that a Map has entries; that is, it must not be <code>null</code>
264: * and must have at least one entry.
265: * <pre>
266: * Assert.notEmpty(map);</pre>
267: * @param map the map to check
268: * @throws IllegalArgumentException if the map is <code>null</code> or has no entries
269: */
270: public static void notEmpty(Map map) {
271: notEmpty(
272: map,
273: "[Assertion failed] - this map must not be empty; it must contain at least one entry");
274: }
275:
276: /**
277: * Assert that the provided object is an instance of the provided class.
278: * <pre>
279: * Assert.instanceOf(Foo.class, foo);</pre>
280: * @param clazz the required class
281: * @param obj the object to check
282: * @throws IllegalArgumentException if the object is not an instance of clazz
283: * @see Class#isInstance
284: */
285: public static void isInstanceOf(Class clazz, Object obj) {
286: isInstanceOf(clazz, obj, "");
287: }
288:
289: /**
290: * Assert that the provided object is an instance of the provided class.
291: * <pre>
292: * Assert.instanceOf(Foo.class, foo);</pre>
293: * @param clazz the required class
294: * @param obj the object to check
295: * @param message a message which will be prepended to the message produced by
296: * the function itself, and which may be used to provide context. It should
297: * normally end in a ":" or ". " so that the function generate message looks
298: * ok when prepended to it.
299: * @throws IllegalArgumentException if the object is not an instance of clazz
300: * @see Class#isInstance
301: */
302: public static void isInstanceOf(Class clazz, Object obj,
303: String message) {
304: Assert
305: .notNull(clazz,
306: "The clazz to perform the instanceof assertion cannot be null");
307: Assert.isTrue(clazz.isInstance(obj), message
308: + "Object of class '"
309: + (obj != null ? obj.getClass().getName() : "[null]")
310: + "' must be an instance of '" + clazz.getName() + "'");
311: }
312:
313: /**
314: * Assert a boolean expression, throwing <code>IllegalStateException</code>
315: * if the test result is <code>false</code>. Call isTrue if you wish to
316: * throw IllegalArgumentException on an assertion failure.
317: * <pre>
318: * Assert.state(id == null, "The id property must not already be initialized");</pre>
319: * @param expression a boolean expression
320: * @param message the exception message to use if the assertion fails
321: * @throws IllegalStateException if expression is <code>false</code>
322: */
323: public static void state(boolean expression, String message) {
324: if (!expression) {
325: throw new IllegalStateException(message);
326: }
327: }
328:
329: /**
330: * Assert a boolean expression, throwing <code>IllegalStateException</code>
331: * if the test result is <code>false</code>. Call isTrue if you wish to
332: * throw IllegalArgumentException on an assertion failure.
333: * <pre>
334: * Assert.state(id == null);</pre>
335: * @param expression a boolean expression
336: * @throws IllegalStateException if expression is <code>false</code>
337: */
338: public static void state(boolean expression) {
339: state(expression,
340: "[Assertion failed] - this state invariant must be true");
341: }
342:
343: }
|