Assert


1   /*
2    * Copyright 2002-2006 the original author or authors.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5    * use this file except in compliance with the License. You may obtain a copy of
6    * the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
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, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations under
14   * the License.
15   */
16  
17  package org.springframework.util;
18  
19  import java.util.Collection  ;
20  import java.util.Map  ;
21  
22  /**
23   * Assertion utility class that assists in validating arguments.
24   * Useful for identifying programmer errors early and clearly at runtime.
25   *
26   * <p>For example, if the contract of a public method states it does not
27   * allow <code>null</code> arguments, Assert can be used to validate that
28   * contract. Doing this clearly indicates a contract violation when it
29   * occurs and protects the class's invariants.
30   *
31   * <p>Typically used to validate method arguments rather than configuration
32   * properties, to check for cases that are usually programmer errors rather than
33   * configuration errors. In contrast to config initialization code, there is
34   * usally no point in falling back to defaults in such methods.
35   *
36   * <p>This class is similar to JUnit's assertion library. If an argument value is
37   * deemed invalid, an {@link IllegalArgumentException} is thrown (typically).
38   * For example:
39   *
40   * <pre class="code">
41   * Assert.notNull(clazz, "The class must not be null");
42   * Assert.isTrue(i > 0, "The value must be greater than zero");</pre>
43   *
44   * Mainly for internal use within the framework; consider Jakarta's Commons Lang
45   * >= 2.0 for a more comprehensive suite of assertion utilities.
46   *
47   * @author Keith Donald
48   * @author Juergen Hoeller
49   * @author Colin Sampaleanu
50   * @author Rob Harrop
51   * @author Erwin Vervaet
52   * @since 1.1.2
53   */
54  public abstract class Assert {
55  
56      /**
57       * Assert a boolean expression, throwing <code>IllegalArgumentException</code>
58       * if the test result is <code>false</code>.
59       * <pre class="code">Assert.isTrue(i &gt; 0, "The value must be greater than zero");</pre>
60       * @param expression a boolean expression
61       * @param message the exception message to use if the assertion fails
62       * @throws IllegalArgumentException if expression is <code>false</code>
63       */
64      public static void isTrue(boolean expression, String   message) {
65          if (!expression) {
66              throw new IllegalArgumentException  (message);
67          }
68      }
69  
70      /**
71       * Assert a boolean expression, throwing <code>IllegalArgumentException</code>
72       * if the test result is <code>false</code>.
73       * <pre class="code">Assert.isTrue(i &gt; 0);</pre>
74       * @param expression a boolean expression
75       * @throws IllegalArgumentException if expression is <code>false</code>
76       */
77      public static void isTrue(boolean expression) {
78          isTrue(expression, "[Assertion failed] - this expression must be true");
79      }
80  
81      /**
82       * Assert that an object is <code>null</code> .
83       * <pre class="code">Assert.isNull(value, "The value must be null");</pre>
84       * @param object the object to check
85       * @param message the exception message to use if the assertion fails
86       * @throws IllegalArgumentException if the object is not <code>null</code>
87       */
88      public static void isNull(Object   object, String   message) {
89          if (object != null) {
90              throw new IllegalArgumentException  (message);
91          }
92      }
93  
94      /**
95       * Assert that an object is <code>null</code> .
96       * <pre class="code">Assert.isNull(value);</pre>
97       * @param object the object to check
98       * @throws IllegalArgumentException if the object is not <code>null</code>
99       */
100     public static void isNull(Object   object) {
101         isNull(object, "[Assertion failed] - the object argument must be null");
102     }
103 
104     /**
105      * Assert that an object is not <code>null</code> .
106      * <pre class="code">Assert.notNull(clazz, "The class must not be null");</pre>
107      * @param object the object to check
108      * @param message the exception message to use if the assertion fails
109      * @throws IllegalArgumentException if the object is <code>null</code>
110      */
111     public static void notNull(Object   object, String   message) {
112         if (object == null) {
113             throw new IllegalArgumentException  (message);
114         }
115     }
116 
117     /**
118      * Assert that an object is not <code>null</code> .
119      * <pre class="code">Assert.notNull(clazz);</pre>
120      * @param object the object to check
121      * @throws IllegalArgumentException if the object is <code>null</code>
122      */
123     public static void notNull(Object   object) {
124         notNull(object, "[Assertion failed] - this argument is required; it must not null");
125     }
126 
127     /**
128      * Assert that a string is not empty; that is, it must not be <code>null</code> and not empty.
129      * <pre class="code">Assert.hasLength(name, "Name must not be empty");</pre>
130      * @param text the string to check
131      * @param message the exception message to use if the assertion fails
132      * @see StringUtils#hasLength
133      */
134     public static void hasLength(String   text, String   message) {
135         if (!StringUtils.hasLength(text)) {
136             throw new IllegalArgumentException  (message);
137         }
138     }
139 
140     /**
141      * Assert that a string is not empty; that is, it must not be <code>null</code> and not empty.
142      * <pre class="code">Assert.hasLength(name);</pre>
143      * @param text the string to check
144      * @see StringUtils#hasLength
145      */
146     public static void hasLength(String   text) {
147         hasLength(text,
148                 "[Assertion failed] - this String argument must have length; it must not be <code>null</code> or empty");
149     }
150 
151     /**
152      * Assert that a string has valid text content; that is, it must not be <code>null</code>
153      * and must contain at least one non-whitespace character.
154      * <pre class="code">Assert.hasText(name, "'name' must not be empty");</pre>
155      * @param text the string to check
156      * @param message the exception message to use if the assertion fails
157      * @see StringUtils#hasText
158      */
159     public static void hasText(String   text, String   message) {
160         if (!StringUtils.hasText(text)) {
161             throw new IllegalArgumentException  (message);
162         }
163     }
164 
165     /**
166      * Assert that a string has valid text content; that is, it must not be <code>null</code>
167      * and must contain at least one non-whitespace character.
168      * <pre class="code">Assert.hasText(name, "'name' must not be empty");</pre>
169      * @param text the string to check
170      * @see StringUtils#hasText
171      */
172     public static void hasText(String   text) {
173         hasText(text,
174                 "[Assertion failed] - this String argument must have text; it must not be <code>null</code>, empty, or blank");
175     }
176 
177     /**
178      * Assert that the given text does not contain the given substring.
179      * <pre class="code">Assert.doesNotContain(name, "rod", "Name must not contain 'rod'");</pre>
180      * @param textToSearch the text to search
181      * @param substring the substring to find within the text
182      * @param message the exception message to use if the assertion fails
183      */
184     public static void doesNotContain(String   textToSearch, String   substring, String   message) {
185         if (StringUtils.hasLength(textToSearch) && StringUtils.hasLength(substring) &&
186                 textToSearch.indexOf(substring) != -1) {
187             throw new IllegalArgumentException  (message);
188         }
189     }
190 
191     /**
192      * Assert that the given text does not contain the given substring.
193      * <pre class="code">Assert.doesNotContain(name, "rod");</pre>
194      * @param textToSearch the text to search
195      * @param substring the substring to find within the text
196      */
197     public static void doesNotContain(String   textToSearch, String   substring) {
198         doesNotContain(textToSearch, substring,
199                 "[Assertion failed] - this String argument must not contain the substring [" + substring + "]");
200     }
201 
202 
203     /**
204      * Assert that an array has elements; that is, it must not be
205      * <code>null</code> and must have at least one element.
206      * <pre class="code">Assert.notEmpty(array, "The array must have elements");</pre>
207      * @param array the array to check
208      * @param message the exception message to use if the assertion fails
209      * @throws IllegalArgumentException if the object array is <code>null</code> or has no elements
210      */
211     public static void notEmpty(Object  [] array, String   message) {
212         if (ObjectUtils.isEmpty(array)) {
213             throw new IllegalArgumentException  (message);
214         }
215     }
216 
217     /**
218      * Assert that an array has elements; that is, it must not be
219      * <code>null</code> and must have at least one element.
220      * <pre class="code">Assert.notEmpty(array);</pre>
221      * @param array the array to check
222      * @throws IllegalArgumentException if the object array is <code>null</code> or has no elements
223      */
224     public static void notEmpty(Object  [] array) {
225         notEmpty(array, "[Assertion failed] - this array must not be empty: it must contain at least 1 element");
226     }
227 
228     /**
229      * Assert that a collection has elements; that is, it must not be
230      * <code>null</code> and must have at least one element.
231      * <pre class="code">Assert.notEmpty(collection, "Collection must have elements");</pre>
232      * @param collection the collection to check
233      * @param message the exception message to use if the assertion fails
234      * @throws IllegalArgumentException if the collection is <code>null</code> or has no elements
235      */
236     public static void notEmpty(Collection   collection, String   message) {
237         if (CollectionUtils.isEmpty(collection)) {
238             throw new IllegalArgumentException  (message);
239         }
240     }
241 
242     /**
243      * Assert that a collection has elements; that is, it must not be
244      * <code>null</code> and must have at least one element.
245      * <pre class="code">Assert.notEmpty(collection, "Collection must have elements");</pre>
246      * @param collection the collection to check
247      * @throws IllegalArgumentException if the collection is <code>null</code> or has no elements
248      */
249     public static void notEmpty(Collection   collection) {
250         notEmpty(collection,
251                 "[Assertion failed] - this collection must not be empty: it must contain at least 1 element");
252     }
253 
254     /**
255      * Assert that a Map has entries; that is, it must not be <code>null</code>
256      * and must have at least one entry.
257      * <pre class="code">Assert.notEmpty(map, "Map must have entries");</pre>
258      * @param map the map to check
259      * @param message the exception message to use if the assertion fails
260      * @throws IllegalArgumentException if the map is <code>null</code> or has no entries
261      */
262     public static void notEmpty(Map   map, String   message) {
263         if (CollectionUtils.isEmpty(map)) {
264             throw new IllegalArgumentException  (message);
265         }
266     }
267 
268     /**
269      * Assert that a Map has entries; that is, it must not be <code>null</code>
270      * and must have at least one entry.
271      * <pre class="code">Assert.notEmpty(map);</pre>
272      * @param map the map to check
273      * @throws IllegalArgumentException if the map is <code>null</code> or has no entries
274      */
275     public static void notEmpty(Map   map) {
276         notEmpty(map, "[Assertion failed] - this map must not be empty; it must contain at least one entry");
277     }
278 
279 
280     /**
281      * Assert that the provided object is an instance of the provided class.
282      * <pre class="code">Assert.instanceOf(Foo.class, foo);</pre>
283      * @param clazz the required class
284      * @param obj the object to check
285      * @throws IllegalArgumentException if the object is not an instance of clazz
286      * @see Class#isInstance
287      */
288     public static void isInstanceOf(Class   clazz, Object   obj) {
289         isInstanceOf(clazz, obj, "");
290     }
291 
292     /**
293      * Assert that the provided object is an instance of the provided class.
294      * <pre class="code">Assert.instanceOf(Foo.class, foo);</pre>
295      * @param type the type to check against
296      * @param obj the object to check
297      * @param message a message which will be prepended to the message produced by
298      * the function itself, and which may be used to provide context. It should
299      * normally end in a ": " or ". " so that the function generate message looks
300      * ok when prepended to it.
301      * @throws IllegalArgumentException if the object is not an instance of clazz
302      * @see Class#isInstance
303      */
304     public static void isInstanceOf(Class   type, Object   obj, String   message) {
305         notNull(type, "Type to check against must not be null");
306         if (!type.isInstance(obj)) {
307             throw new IllegalArgumentException  (message +
308                     "Object of class [" + (obj != null ? obj.getClass().getName() : "null") +
309                     "] must be an instance of " + type);
310         }
311     }
312 
313     /**
314      * Assert that <code>superType.isAssignableFrom(subType)</code> is <code>true</code>.
315      * <pre class="code">Assert.isAssignable(Number.class, myClass);</pre>
316      * @param superType the super type to check
317      * @param subType the sub type to check
318      * @throws IllegalArgumentException if the classes are not assignable
319      */
320     public static void isAssignable(Class   superType, Class   subType) {
321         isAssignable(superType, subType, "");
322     }
323 
324     /**
325      * Assert that <code>superType.isAssignableFrom(subType)</code> is <code>true</code>.
326      * <pre class="code">Assert.isAssignable(Number.class, myClass);</pre>
327      * @param superType the super type to check against
328      * @param subType the sub type to check
329      * @param message a message which will be prepended to the message produced by
330      * the function itself, and which may be used to provide context. It should
331      * normally end in a ": " or ". " so that the function generate message looks
332      * ok when prepended to it.
333      * @throws IllegalArgumentException if the classes are not assignable
334      */
335     public static void isAssignable(Class   superType, Class   subType, String   message) {
336         notNull(superType, "Type to check against must not be null");
337         if (subType == null || !superType.isAssignableFrom(subType)) {
338             throw new IllegalArgumentException  (message + subType + " is not assignable to " + superType);
339         }
340     }
341 
342 
343     /**
344      * Assert a boolean expression, throwing <code>IllegalStateException</code>
345      * if the test result is <code>false</code>. Call isTrue if you wish to
346      * throw IllegalArgumentException on an assertion failure.
347      * <pre class="code">Assert.state(id == null, "The id property must not already be initialized");</pre>
348      * @param expression a boolean expression
349      * @param message the exception message to use if the assertion fails
350      * @throws IllegalStateException if expression is <code>false</code>
351      */
352     public static void state(boolean expression, String   message) {
353         if (!expression) {
354             throw new IllegalStateException  (message);
355         }
356     }
357 
358     /**
359      * Assert a boolean expression, throwing {@link IllegalStateException}
360      * if the test result is <code>false</code>.
361      * <p>Call {@link #isTrue(boolean)} if you wish to
362      * throw {@link IllegalArgumentException} on an assertion failure.
363      * <pre class="code">Assert.state(id == null);</pre>
364      * @param expression a boolean expression
365      * @throws IllegalStateException if the supplied expression is <code>false</code>
366      */
367     public static void state(boolean expression) {
368         state(expression, "[Assertion failed] - this state invariant must be true");
369     }
370 
371 }
372
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags