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