001: /*
002: * Copyright 2002-2007 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005: * use this file except in compliance with the License. You may obtain a copy of
006: * 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, WITHOUT
012: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013: * License for the specific language governing permissions and limitations under
014: * the License.
015: */
016:
017: package org.springframework.util;
018:
019: import java.util.Collection;
020: import java.util.Map;
021:
022: /**
023: * Assertion utility class that assists in validating arguments.
024: * Useful for identifying programmer errors early and clearly at runtime.
025: *
026: * <p>For example, if the contract of a public method states it does not
027: * allow <code>null</code> arguments, Assert can be used to validate that
028: * contract. Doing this clearly indicates a contract violation when it
029: * occurs and protects the class's 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 {@link IllegalArgumentException} is thrown (typically).
038: * For example:
039: *
040: * <pre class="code">
041: * Assert.notNull(clazz, "The class must not be null");
042: * Assert.isTrue(i > 0, "The value must be greater than zero");</pre>
043: *
044: * Mainly for internal use within the framework; consider Jakarta's Commons Lang
045: * >= 2.0 for a more comprehensive suite of assertion utilities.
046: *
047: * @author Keith Donald
048: * @author Juergen Hoeller
049: * @author Colin Sampaleanu
050: * @author Rob Harrop
051: * @since 1.1.2
052: */
053: public abstract class Assert {
054:
055: /**
056: * Assert a boolean expression, throwing <code>IllegalArgumentException</code>
057: * if the test result is <code>false</code>.
058: * <pre class="code">Assert.isTrue(i > 0, "The value must be greater than zero");</pre>
059: * @param expression a boolean expression
060: * @param message the exception message to use if the assertion fails
061: * @throws IllegalArgumentException if expression is <code>false</code>
062: */
063: public static void isTrue(boolean expression, String message) {
064: if (!expression) {
065: throw new IllegalArgumentException(message);
066: }
067: }
068:
069: /**
070: * Assert a boolean expression, throwing <code>IllegalArgumentException</code>
071: * if the test result is <code>false</code>.
072: * <pre class="code">Assert.isTrue(i > 0);</pre>
073: * @param expression a boolean expression
074: * @throws IllegalArgumentException if expression is <code>false</code>
075: */
076: public static void isTrue(boolean expression) {
077: isTrue(expression,
078: "[Assertion failed] - this expression must be true");
079: }
080:
081: /**
082: * Assert that an object is <code>null</code> .
083: * <pre class="code">Assert.isNull(value, "The value must be null");</pre>
084: * @param object the object to check
085: * @param message the exception message to use if the assertion fails
086: * @throws IllegalArgumentException if the object is not <code>null</code>
087: */
088: public static void isNull(Object object, String message) {
089: if (object != null) {
090: throw new IllegalArgumentException(message);
091: }
092: }
093:
094: /**
095: * Assert that an object is <code>null</code> .
096: * <pre class="code">Assert.isNull(value);</pre>
097: * @param object the object to check
098: * @throws IllegalArgumentException if the object is not <code>null</code>
099: */
100: public static void isNull(Object object) {
101: isNull(object,
102: "[Assertion failed] - the object argument must be null");
103: }
104:
105: /**
106: * Assert that an object is not <code>null</code> .
107: * <pre class="code">Assert.notNull(clazz, "The class must not be null");</pre>
108: * @param object the object to check
109: * @param message the exception message to use if the assertion fails
110: * @throws IllegalArgumentException if the object is <code>null</code>
111: */
112: public static void notNull(Object object, String message) {
113: if (object == null) {
114: throw new IllegalArgumentException(message);
115: }
116: }
117:
118: /**
119: * Assert that an object is not <code>null</code> .
120: * <pre class="code">Assert.notNull(clazz);</pre>
121: * @param object the object to check
122: * @throws IllegalArgumentException if the object is <code>null</code>
123: */
124: public static void notNull(Object object) {
125: notNull(object,
126: "[Assertion failed] - this argument is required; it must not be null");
127: }
128:
129: /**
130: * Assert that the given String is not empty; that is,
131: * it must not be <code>null</code> and not the empty String.
132: * <pre class="code">Assert.hasLength(name, "Name must not be empty");</pre>
133: * @param text the String to check
134: * @param message the exception message to use if the assertion fails
135: * @see StringUtils#hasLength
136: */
137: public static void hasLength(String text, String message) {
138: if (!StringUtils.hasLength(text)) {
139: throw new IllegalArgumentException(message);
140: }
141: }
142:
143: /**
144: * Assert that the given String is not empty; that is,
145: * it must not be <code>null</code> and not the empty String.
146: * <pre class="code">Assert.hasLength(name);</pre>
147: * @param text the String to check
148: * @see StringUtils#hasLength
149: */
150: public static void hasLength(String text) {
151: hasLength(
152: text,
153: "[Assertion failed] - this String argument must have length; it must not be <code>null</code> or empty");
154: }
155:
156: /**
157: * Assert that the given String has valid text content; that is, it must not
158: * be <code>null</code> and must contain at least one non-whitespace character.
159: * <pre class="code">Assert.hasText(name, "'name' must not be empty");</pre>
160: * @param text the String to check
161: * @param message the exception message to use if the assertion fails
162: * @see StringUtils#hasText
163: */
164: public static void hasText(String text, String message) {
165: if (!StringUtils.hasText(text)) {
166: throw new IllegalArgumentException(message);
167: }
168: }
169:
170: /**
171: * Assert that the given String has valid text content; that is, it must not
172: * be <code>null</code> and must contain at least one non-whitespace character.
173: * <pre class="code">Assert.hasText(name, "'name' must not be empty");</pre>
174: * @param text the String to check
175: * @see StringUtils#hasText
176: */
177: public static void hasText(String text) {
178: hasText(
179: text,
180: "[Assertion failed] - this String argument must have text; it must not be <code>null</code>, empty, or blank");
181: }
182:
183: /**
184: * Assert that the given text does not contain the given substring.
185: * <pre class="code">Assert.doesNotContain(name, "rod", "Name must not contain 'rod'");</pre>
186: * @param textToSearch the text to search
187: * @param substring the substring to find within the text
188: * @param message the exception message to use if the assertion fails
189: */
190: public static void doesNotContain(String textToSearch,
191: String substring, String message) {
192: if (StringUtils.hasLength(textToSearch)
193: && StringUtils.hasLength(substring)
194: && textToSearch.indexOf(substring) != -1) {
195: throw new IllegalArgumentException(message);
196: }
197: }
198:
199: /**
200: * Assert that the given text does not contain the given substring.
201: * <pre class="code">Assert.doesNotContain(name, "rod");</pre>
202: * @param textToSearch the text to search
203: * @param substring the substring to find within the text
204: */
205: public static void doesNotContain(String textToSearch,
206: String substring) {
207: doesNotContain(textToSearch, substring,
208: "[Assertion failed] - this String argument must not contain the substring ["
209: + substring + "]");
210: }
211:
212: /**
213: * Assert that an array has elements; that is, it must not be
214: * <code>null</code> and must have at least one element.
215: * <pre class="code">Assert.notEmpty(array, "The array must have elements");</pre>
216: * @param array the array to check
217: * @param message the exception message to use if the assertion fails
218: * @throws IllegalArgumentException if the object array is <code>null</code> or has no elements
219: */
220: public static void notEmpty(Object[] array, String message) {
221: if (ObjectUtils.isEmpty(array)) {
222: throw new IllegalArgumentException(message);
223: }
224: }
225:
226: /**
227: * Assert that an array has elements; that is, it must not be
228: * <code>null</code> and must have at least one element.
229: * <pre class="code">Assert.notEmpty(array);</pre>
230: * @param array the array to check
231: * @throws IllegalArgumentException if the object array is <code>null</code> or has no elements
232: */
233: public static void notEmpty(Object[] array) {
234: notEmpty(
235: array,
236: "[Assertion failed] - this array must not be empty: it must contain at least 1 element");
237: }
238:
239: /**
240: * Assert that a collection has elements; that is, it must not be
241: * <code>null</code> and must have at least one element.
242: * <pre class="code">Assert.notEmpty(collection, "Collection must have elements");</pre>
243: * @param collection the collection to check
244: * @param message the exception message to use if the assertion fails
245: * @throws IllegalArgumentException if the collection is <code>null</code> or has no elements
246: */
247: public static void notEmpty(Collection collection, String message) {
248: if (CollectionUtils.isEmpty(collection)) {
249: throw new IllegalArgumentException(message);
250: }
251: }
252:
253: /**
254: * Assert that a collection has elements; that is, it must not be
255: * <code>null</code> and must have at least one element.
256: * <pre class="code">Assert.notEmpty(collection, "Collection must have elements");</pre>
257: * @param collection the collection to check
258: * @throws IllegalArgumentException if the collection is <code>null</code> or has no elements
259: */
260: public static void notEmpty(Collection collection) {
261: notEmpty(
262: collection,
263: "[Assertion failed] - this collection must not be empty: it must contain at least 1 element");
264: }
265:
266: /**
267: * Assert that a Map has entries; that is, it must not be <code>null</code>
268: * and must have at least one entry.
269: * <pre class="code">Assert.notEmpty(map, "Map must have entries");</pre>
270: * @param map the map to check
271: * @param message the exception message to use if the assertion fails
272: * @throws IllegalArgumentException if the map is <code>null</code> or has no entries
273: */
274: public static void notEmpty(Map map, String message) {
275: if (CollectionUtils.isEmpty(map)) {
276: throw new IllegalArgumentException(message);
277: }
278: }
279:
280: /**
281: * Assert that a Map has entries; that is, it must not be <code>null</code>
282: * and must have at least one entry.
283: * <pre class="code">Assert.notEmpty(map);</pre>
284: * @param map the map to check
285: * @throws IllegalArgumentException if the map is <code>null</code> or has no entries
286: */
287: public static void notEmpty(Map map) {
288: notEmpty(
289: map,
290: "[Assertion failed] - this map must not be empty; it must contain at least one entry");
291: }
292:
293: /**
294: * Assert that the provided object is an instance of the provided class.
295: * <pre class="code">Assert.instanceOf(Foo.class, foo);</pre>
296: * @param clazz the required class
297: * @param obj the object to check
298: * @throws IllegalArgumentException if the object is not an instance of clazz
299: * @see Class#isInstance
300: */
301: public static void isInstanceOf(Class clazz, Object obj) {
302: isInstanceOf(clazz, obj, "");
303: }
304:
305: /**
306: * Assert that the provided object is an instance of the provided class.
307: * <pre class="code">Assert.instanceOf(Foo.class, foo);</pre>
308: * @param type the type to check against
309: * @param obj the object to check
310: * @param message a message which will be prepended to the message produced by
311: * the function itself, and which may be used to provide context. It should
312: * normally end in a ": " or ". " so that the function generate message looks
313: * ok when prepended to it.
314: * @throws IllegalArgumentException if the object is not an instance of clazz
315: * @see Class#isInstance
316: */
317: public static void isInstanceOf(Class type, Object obj,
318: String message) {
319: notNull(type, "Type to check against must not be null");
320: if (!type.isInstance(obj)) {
321: throw new IllegalArgumentException(message
322: + "Object of class ["
323: + (obj != null ? obj.getClass().getName() : "null")
324: + "] must be an instance of " + type);
325: }
326: }
327:
328: /**
329: * Assert that <code>superType.isAssignableFrom(subType)</code> is <code>true</code>.
330: * <pre class="code">Assert.isAssignable(Number.class, myClass);</pre>
331: * @param superType the super type to check
332: * @param subType the sub type to check
333: * @throws IllegalArgumentException if the classes are not assignable
334: */
335: public static void isAssignable(Class super Type, Class subType) {
336: isAssignable(super Type, subType, "");
337: }
338:
339: /**
340: * Assert that <code>superType.isAssignableFrom(subType)</code> is <code>true</code>.
341: * <pre class="code">Assert.isAssignable(Number.class, myClass);</pre>
342: * @param superType the super type to check against
343: * @param subType the sub type to check
344: * @param message a message which will be prepended to the message produced by
345: * the function itself, and which may be used to provide context. It should
346: * normally end in a ": " or ". " so that the function generate message looks
347: * ok when prepended to it.
348: * @throws IllegalArgumentException if the classes are not assignable
349: */
350: public static void isAssignable(Class super Type, Class subType,
351: String message) {
352: notNull(super Type, "Type to check against must not be null");
353: if (subType == null || !super Type.isAssignableFrom(subType)) {
354: throw new IllegalArgumentException(message + subType
355: + " is not assignable to " + super Type);
356: }
357: }
358:
359: /**
360: * Assert a boolean expression, throwing <code>IllegalStateException</code>
361: * if the test result is <code>false</code>. Call isTrue if you wish to
362: * throw IllegalArgumentException on an assertion failure.
363: * <pre class="code">Assert.state(id == null, "The id property must not already be initialized");</pre>
364: * @param expression a boolean expression
365: * @param message the exception message to use if the assertion fails
366: * @throws IllegalStateException if expression is <code>false</code>
367: */
368: public static void state(boolean expression, String message) {
369: if (!expression) {
370: throw new IllegalStateException(message);
371: }
372: }
373:
374: /**
375: * Assert a boolean expression, throwing {@link IllegalStateException}
376: * if the test result is <code>false</code>.
377: * <p>Call {@link #isTrue(boolean)} if you wish to
378: * throw {@link IllegalArgumentException} on an assertion failure.
379: * <pre class="code">Assert.state(id == null);</pre>
380: * @param expression a boolean expression
381: * @throws IllegalStateException if the supplied expression is <code>false</code>
382: */
383: public static void state(boolean expression) {
384: state(expression,
385: "[Assertion failed] - this state invariant must be true");
386: }
387:
388: }
|