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 null");
127: }
128:
129: /**
130: * Assert that a string is not empty; that is, it must not be <code>null</code> and not empty.
131: * <pre class="code">Assert.hasLength(name, "Name must not be empty");</pre>
132: * @param text the string to check
133: * @param message the exception message to use if the assertion fails
134: * @see StringUtils#hasLength
135: */
136: public static void hasLength(String text, String message) {
137: if (!StringUtils.hasLength(text)) {
138: throw new IllegalArgumentException(message);
139: }
140: }
141:
142: /**
143: * Assert that a string is not empty; that is, it must not be <code>null</code> and not empty.
144: * <pre class="code">Assert.hasLength(name);</pre>
145: * @param text the string to check
146: * @see StringUtils#hasLength
147: */
148: public static void hasLength(String text) {
149: hasLength(
150: text,
151: "[Assertion failed] - this String argument must have length; it must not be <code>null</code> or empty");
152: }
153:
154: /**
155: * Assert that a string has valid text content; that is, it must not be <code>null</code>
156: * and must contain at least one non-whitespace character.
157: * <pre class="code">Assert.hasText(name, "'name' must not be empty");</pre>
158: * @param text the string to check
159: * @param message the exception message to use if the assertion fails
160: * @see StringUtils#hasText
161: */
162: public static void hasText(String text, String message) {
163: if (!StringUtils.hasText(text)) {
164: throw new IllegalArgumentException(message);
165: }
166: }
167:
168: /**
169: * Assert that a string has valid text content; that is, it must not be <code>null</code>
170: * and must contain at least one non-whitespace character.
171: * <pre class="code">Assert.hasText(name, "'name' must not be empty");</pre>
172: * @param text the string to check
173: * @see StringUtils#hasText
174: */
175: public static void hasText(String text) {
176: hasText(
177: text,
178: "[Assertion failed] - this String argument must have text; it must not be <code>null</code>, empty, or blank");
179: }
180:
181: /**
182: * Assert that the given text does not contain the given substring.
183: * <pre class="code">Assert.doesNotContain(name, "rod", "Name must not contain 'rod'");</pre>
184: * @param textToSearch the text to search
185: * @param substring the substring to find within the text
186: * @param message the exception message to use if the assertion fails
187: */
188: public static void doesNotContain(String textToSearch,
189: String substring, String message) {
190: if (StringUtils.hasLength(textToSearch)
191: && StringUtils.hasLength(substring)
192: && textToSearch.indexOf(substring) != -1) {
193: throw new IllegalArgumentException(message);
194: }
195: }
196:
197: /**
198: * Assert that the given text does not contain the given substring.
199: * <pre class="code">Assert.doesNotContain(name, "rod");</pre>
200: * @param textToSearch the text to search
201: * @param substring the substring to find within the text
202: */
203: public static void doesNotContain(String textToSearch,
204: String substring) {
205: doesNotContain(textToSearch, substring,
206: "[Assertion failed] - this String argument must not contain the substring ["
207: + substring + "]");
208: }
209:
210: /**
211: * Assert that an array has elements; that is, it must not be
212: * <code>null</code> and must have at least one element.
213: * <pre class="code">Assert.notEmpty(array, "The array must have elements");</pre>
214: * @param array the array to check
215: * @param message the exception message to use if the assertion fails
216: * @throws IllegalArgumentException if the object array is <code>null</code> or has no elements
217: */
218: public static void notEmpty(Object[] array, String message) {
219: if (ObjectUtils.isEmpty(array)) {
220: throw new IllegalArgumentException(message);
221: }
222: }
223:
224: /**
225: * Assert that an array has elements; that is, it must not be
226: * <code>null</code> and must have at least one element.
227: * <pre class="code">Assert.notEmpty(array);</pre>
228: * @param array the array to check
229: * @throws IllegalArgumentException if the object array is <code>null</code> or has no elements
230: */
231: public static void notEmpty(Object[] array) {
232: notEmpty(
233: array,
234: "[Assertion failed] - this array must not be empty: it must contain at least 1 element");
235: }
236:
237: /**
238: * Assert that a collection has elements; that is, it must not be
239: * <code>null</code> and must have at least one element.
240: * <pre class="code">Assert.notEmpty(collection, "Collection must have elements");</pre>
241: * @param collection the collection to check
242: * @param message the exception message to use if the assertion fails
243: * @throws IllegalArgumentException if the collection is <code>null</code> or has no elements
244: */
245: public static void notEmpty(Collection collection, String message) {
246: if (CollectionUtils.isEmpty(collection)) {
247: throw new IllegalArgumentException(message);
248: }
249: }
250:
251: /**
252: * Assert that a collection has elements; that is, it must not be
253: * <code>null</code> and must have at least one element.
254: * <pre class="code">Assert.notEmpty(collection, "Collection must have elements");</pre>
255: * @param collection the collection to check
256: * @throws IllegalArgumentException if the collection is <code>null</code> or has no elements
257: */
258: public static void notEmpty(Collection collection) {
259: notEmpty(
260: collection,
261: "[Assertion failed] - this collection must not be empty: it must contain at least 1 element");
262: }
263:
264: /**
265: * Assert that a Map has entries; that is, it must not be <code>null</code>
266: * and must have at least one entry.
267: * <pre class="code">Assert.notEmpty(map, "Map must have entries");</pre>
268: * @param map the map to check
269: * @param message the exception message to use if the assertion fails
270: * @throws IllegalArgumentException if the map is <code>null</code> or has no entries
271: */
272: public static void notEmpty(Map map, String message) {
273: if (CollectionUtils.isEmpty(map)) {
274: throw new IllegalArgumentException(message);
275: }
276: }
277:
278: /**
279: * Assert that a Map has entries; that is, it must not be <code>null</code>
280: * and must have at least one entry.
281: * <pre class="code">Assert.notEmpty(map);</pre>
282: * @param map the map to check
283: * @throws IllegalArgumentException if the map is <code>null</code> or has no entries
284: */
285: public static void notEmpty(Map map) {
286: notEmpty(
287: map,
288: "[Assertion failed] - this map must not be empty; it must contain at least one entry");
289: }
290:
291: /**
292: * Assert that the provided object is an instance of the provided class.
293: * <pre class="code">Assert.instanceOf(Foo.class, foo);</pre>
294: * @param clazz the required class
295: * @param obj the object to check
296: * @throws IllegalArgumentException if the object is not an instance of clazz
297: * @see Class#isInstance
298: */
299: public static void isInstanceOf(Class clazz, Object obj) {
300: isInstanceOf(clazz, obj, "");
301: }
302:
303: /**
304: * Assert that the provided object is an instance of the provided class.
305: * <pre class="code">Assert.instanceOf(Foo.class, foo);</pre>
306: * @param type the type to check against
307: * @param obj the object to check
308: * @param message a message which will be prepended to the message produced by
309: * the function itself, and which may be used to provide context. It should
310: * normally end in a ": " or ". " so that the function generate message looks
311: * ok when prepended to it.
312: * @throws IllegalArgumentException if the object is not an instance of clazz
313: * @see Class#isInstance
314: */
315: public static void isInstanceOf(Class type, Object obj,
316: String message) {
317: notNull(type, "Type to check against must not be null");
318: if (!type.isInstance(obj)) {
319: throw new IllegalArgumentException(message
320: + "Object of class ["
321: + (obj != null ? obj.getClass().getName() : "null")
322: + "] must be an instance of " + type);
323: }
324: }
325:
326: /**
327: * Assert that <code>superType.isAssignableFrom(subType)</code> is <code>true</code>.
328: * <pre class="code">Assert.isAssignable(Number.class, myClass);</pre>
329: * @param superType the super type to check
330: * @param subType the sub type to check
331: * @throws IllegalArgumentException if the classes are not assignable
332: */
333: public static void isAssignable(Class super Type, Class subType) {
334: isAssignable(super Type, subType, "");
335: }
336:
337: /**
338: * Assert that <code>superType.isAssignableFrom(subType)</code> is <code>true</code>.
339: * <pre class="code">Assert.isAssignable(Number.class, myClass);</pre>
340: * @param superType the super type to check against
341: * @param subType the sub type to check
342: * @param message a message which will be prepended to the message produced by
343: * the function itself, and which may be used to provide context. It should
344: * normally end in a ": " or ". " so that the function generate message looks
345: * ok when prepended to it.
346: * @throws IllegalArgumentException if the classes are not assignable
347: */
348: public static void isAssignable(Class super Type, Class subType,
349: String message) {
350: notNull(super Type, "Type to check against must not be null");
351: if (subType == null || !super Type.isAssignableFrom(subType)) {
352: throw new IllegalArgumentException(message + subType
353: + " is not assignable to " + super Type);
354: }
355: }
356:
357: /**
358: * Assert a boolean expression, throwing <code>IllegalStateException</code>
359: * if the test result is <code>false</code>. Call isTrue if you wish to
360: * throw IllegalArgumentException on an assertion failure.
361: * <pre class="code">Assert.state(id == null, "The id property must not already be initialized");</pre>
362: * @param expression a boolean expression
363: * @param message the exception message to use if the assertion fails
364: * @throws IllegalStateException if expression is <code>false</code>
365: */
366: public static void state(boolean expression, String message) {
367: if (!expression) {
368: throw new IllegalStateException(message);
369: }
370: }
371:
372: /**
373: * Assert a boolean expression, throwing {@link IllegalStateException}
374: * if the test result is <code>false</code>.
375: * <p>Call {@link #isTrue(boolean)} if you wish to
376: * throw {@link IllegalArgumentException} on an assertion failure.
377: * <pre class="code">Assert.state(id == null);</pre>
378: * @param expression a boolean expression
379: * @throws IllegalStateException if the supplied expression is <code>false</code>
380: */
381: public static void state(boolean expression) {
382: state(expression,
383: "[Assertion failed] - this state invariant must be true");
384: }
385:
386: }
|