View Javadoc

1   /*
2    * File:    ContractChecker.java
3    * Created: 13.10.2006 8:52:33 
4    *
5    * Copyright 2006 Michal Burda.
6    *
7    * This program is free software; you can redistribute it and/or modify
8    * it under the terms of the GNU General Public License as published by
9    * the Free Software Foundation; either version 2 of the License, or
10   * (at your option) any later version.
11   *
12   * This program is distributed in the hope that it will be useful,
13   * but WITHOUT ANY WARRANTY; without even the implied warranty of
14   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15   * GNU General Public License for more details.
16   *
17   * You should have received a copy of the GNU General Public License
18   * along with this program; if not, write to the Free Software
19   * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
20   */
21  package net.sf.webmancer.util;
22  
23  import java.util.Iterator;
24  
25  /**
26   * This class defines a set of methods for contract checking.
27   * 
28   * @author Michal Burda
29   */
30  public class ContractChecker {
31      /**
32       * Prevent from instantiation
33       */
34      private ContractChecker() {
35          // prevent from instantiation
36      }
37  
38      /**
39       * Throw the {@link IllegalStateException} with the given <code>errorMessage</code> if the <code>legalState</code>
40       * is <code>false</code>.
41       * 
42       * @param legalState
43       *            The state to be checked
44       * @param errorMessage
45       *            The error message
46       * @throws IllegalStateException
47       *             Thrown if the <code>legalState</code> is <code>false</code>
48       */
49      public static void checkState(boolean legalState, final String errorMessage) throws IllegalStateException {
50          if (!legalState) {
51              throw new IllegalStateException(errorMessage);
52          }
53      }
54  
55      /**
56       * Throws the {@link IllegalArgumentException} if the given <code>condition</code> is <code>false</code>.
57       * 
58       * @param condition
59       *            The condition that must be <code>true</code> or the exception is thrown
60       * @param message
61       *            The error message
62       * @throws IllegalArgumentException
63       *             Thrown if the <code>condition</code> is <code>false</code>
64       */
65      public static void mustBe(boolean condition, final String message) throws IllegalArgumentException {
66          if (!condition) {
67              throw new IllegalArgumentException(message);
68          }
69      }
70  
71      /**
72       * Throws the {@link IllegalArgumentException} if the given <code>parameter</code> is not an instance of class <code>clazz</code>.
73       * 
74       * @param parameter The parameter being checked
75       * @param clazz The reference class
76       * @param name The name of the parameter being checked
77       * @throws IllegalArgumentException Thrown if the checked condition is not satisfied
78       */
79      public static void mustBeInstanceOf(final Object parameter, final Class clazz, final String name) throws IllegalArgumentException {
80          if (!clazz.isInstance(parameter)) {
81              throw new IllegalArgumentException(name + " must be of type " + clazz);
82          }
83      }
84  
85      /**
86       * Throws the {@link IllegalArgumentException} if the given <code>parameter</code> is not an instance of either
87       * class in <code>classes</code>.
88       * 
89       * @param parameter The parameter being checked
90       * @param classes The array of classes
91       * @param name The name of the parameter being checked
92       * @throws IllegalArgumentException Thrown if the checked condition is not satisfied
93       */
94      public static void mustBeInstanceOf(final Object parameter, final Class[] classes, final String name) throws IllegalArgumentException {
95          if (classes == null || classes.length == 0) {
96              throw new IllegalArgumentException("Wrong call of contract checking method");
97          }
98          // firstly, test the contract
99          for (Class clazz : classes) {
100             if (clazz.isInstance(parameter)) {
101                 return;
102             }
103         }
104         // if failed, contstruct the exception
105         StringBuffer buf = new StringBuffer(name);
106         buf.append(" must be an either type of: [");
107         buf.append(classes[0].toString());
108         for (int i = 1; i < classes.length; i++) {
109             buf.append(", ");
110             buf.append(classes[i]);
111         }
112         buf.append("]");
113         throw new IllegalArgumentException(buf.toString());
114     }
115     
116     /**
117      * Throws the {@link IllegalArgumentException} if the given <code>parameter</code> is <code>null</code>.
118      * 
119      * @param parameter
120      *            The parameter that has to be non-<code>null</code>
121      * @param name
122      *            The name of the parameter being checked
123      * @throws NullPointerException
124      *             Thrown if the checked condition is not satisfied
125      */
126     public static void mustNotBeNull(final Object parameter, final String name) throws NullPointerException {
127         if (parameter == null) {
128             throw new NullPointerException(name + " must not be null");
129         }
130     }
131 
132     /**
133      * Throws the {@link IllegalArgumentException} if the given <code>parameter</code> is <code>null</code> or empty
134      * string (after trim).
135      * 
136      * @param parameter
137      *            The parameter that has to be non-<code>null</code> and non-empty string
138      * @param name
139      *            The name of the parameter being checked
140      * @throws IllegalArgumentException
141      *             Thrown if the checked condition is not satisfied
142      */
143     public static void mustNotBeEmpty(final String parameter, final String name) throws IllegalArgumentException {
144         if (parameter == null || parameter.trim().length() <= 0) {
145             throw new IllegalArgumentException(name + " must not be empty string (was: <" + parameter + ">)");
146         }
147     }
148 
149     /**
150      * Throws the {@link IllegalArgumentException} if the given <code>parameter</code> is <code>null</code> or an
151      * array of size 0.
152      * 
153      * @param parameter
154      *            The parameter that has to be non-<code>null</code> and non-zero-length array
155      * @param name
156      *            The name of the parameter being checked
157      * @throws IllegalArgumentException
158      *             Thrown if the checked condition is not satisfied
159      */
160     public static void mustNotBeEmpty(final Object[] parameter, final String name) throws IllegalArgumentException {
161         if (parameter == null || parameter.length <= 0) {
162             throw new IllegalArgumentException(name + " must not be empty array (was: <" + parameter + ">)");
163         }
164     }
165 
166     /**
167      * Throws the {@link IllegalArgumentException} if the given <code>parameter</code> is greater or equal to zero.
168      * 
169      * @param parameter
170      *            The parameter that has to be negative
171      * @param name
172      *            The name of the parameter being checked
173      * @throws IllegalArgumentException
174      *             Thrown if the checked condition is not satisfied
175      */
176     public static void mustBeNegative(final double parameter, final String name) throws IllegalArgumentException {
177         if (parameter >= 0) {
178             throw new IllegalArgumentException(name + " must be negative (was: <" + parameter + ">)");
179         }
180     }
181 
182     /**
183      * Throws the {@link IllegalArgumentException} if the given <code>parameter</code> is lower or equal to zero.
184      * 
185      * @param parameter
186      *            The parameter that has to be positive
187      * @param name
188      *            The name of the parameter being checked
189      * @throws IllegalArgumentException
190      *             Thrown if the checked condition is not satisfied
191      */
192     public static void mustBePositive(final double parameter, final String name) throws IllegalArgumentException {
193         if (parameter <= 0) {
194             throw new IllegalArgumentException(name + " must be positive (was: <" + parameter + ">)");
195         }
196     }
197 
198     /**
199      * Throws the {@link IllegalArgumentException} if the given <code>parameter</code> is lower than zero.
200      * 
201      * @param parameter
202      *            The parameter that has to be positive or zero
203      * @param name
204      *            The name of the parameter being checked
205      * @throws IllegalArgumentException
206      *             Thrown if the checked condition is not satisfied
207      */
208     public static void mustNotBeNegative(final double parameter, final String name) throws IllegalArgumentException {
209         if (parameter < 0) {
210             throw new IllegalArgumentException(name + " must not be negative (was: <" + parameter + ">)");
211         }
212     }
213 
214     /**
215      * Throws the {@link IllegalArgumentException} if the given <code>parameter</code> is greater than zero.
216      * 
217      * @param parameter
218      *            The parameter that has to be negative or zero
219      * @param name
220      *            The name of the parameter being checked
221      * @throws IllegalArgumentException
222      *             Thrown if the checked condition is not satisfied
223      */
224     public static void mustNotBePositive(final double parameter, final String name) throws IllegalArgumentException {
225         if (parameter > 0) {
226             throw new IllegalArgumentException(name + " must not be positive (was: <" + parameter + ">)");
227         }
228     }
229 
230     /**
231      * Throws the {@link IllegalArgumentException} if the given <code>parameter</code> is equal to zero
232      * 
233      * @param parameter
234      *            The parameter that has to be non-zero
235      * @param name
236      *            The name of the parameter being checked
237      * @throws IllegalArgumentException
238      *             Thrown if the checked condition is not satisfied
239      */
240     public static void mustNotBeZero(final double parameter, final String name) throws IllegalArgumentException {
241         if (parameter == 0) {
242             throw new IllegalArgumentException(name + " must not be zero (was: <" + parameter + ">)");
243         }
244     }
245 
246     /**
247      * Throws the {@link IllegalArgumentException} if the given <code>parameter</code> is lower or equal to the given
248      * reference value <code>ref</code>.
249      * 
250      * @param parameter
251      *            The parameter that has to be greater than given reference value <code>ref</code>
252      * @param ref
253      *            The reference value the parameter is compared to
254      * @param name
255      *            The name of the parameter being checked
256      * @throws IllegalArgumentException
257      *             Thrown if the checked condition is not satisfied
258      */
259     public static void mustBeGreater(final double parameter, final double ref, final String name) throws IllegalArgumentException {
260         if (parameter <= ref) {
261             throw new IllegalArgumentException(name + " must be greater than " + ref + " (was: <" + parameter + ">)");
262         }
263     }
264 
265     /**
266      * Throws the {@link IllegalArgumentException} if the given <code>parameter</code> is lower than the given
267      * reference value <code>ref</code>.
268      * 
269      * @param parameter
270      *            The parameter that has to be greater or equal to the given reference value <code>ref</code>
271      * @param ref
272      *            The reference value the parameter is compared to
273      * @param name
274      *            The name of the parameter being checked
275      * @throws IllegalArgumentException
276      *             Thrown if the checked condition is not satisfied
277      */
278     public static void mustBeGreaterEq(final double parameter, final double ref, final String name) throws IllegalArgumentException {
279         if (parameter < ref) {
280             throw new IllegalArgumentException(name + " must be greater or equal to " + ref + " (was: <" + parameter
281                     + ">)");
282         }
283     }
284 
285     /**
286      * Throws the {@link IllegalArgumentException} if the given <code>parameter</code> is greater or equal to the
287      * given reference value <code>ref</code>.
288      * 
289      * @param parameter
290      *            The parameter that has to be lower than given reference value <code>ref</code>
291      * @param ref
292      *            The reference value the parameter is compared to
293      * @param name
294      *            The name of the parameter being checked
295      * @throws IllegalArgumentException
296      *             Thrown if the checked condition is not satisfied
297      */
298     public static void mustBeLess(final double parameter, final double ref, final String name) throws IllegalArgumentException {
299         if (parameter >= ref) {
300             throw new IllegalArgumentException(name + " must be less than " + ref + " (was: <" + parameter + ">)");
301         }
302     }
303 
304     /**
305      * Throws the {@link IllegalArgumentException} if the given <code>parameter</code> is greater than the given
306      * reference value <code>ref</code>.
307      * 
308      * @param parameter
309      *            The parameter that has to be lower or equal to the given reference value <code>ref</code>
310      * @param ref
311      *            The reference value the parameter is compared to
312      * @param name
313      *            The name of the parameter being checked
314      * @throws IllegalArgumentException
315      *             Thrown if the checked condition is not satisfied
316      */
317     public static void mustBeLessEq(final double parameter, final double ref, final String name) throws IllegalArgumentException {
318         if (parameter > ref) {
319             throw new IllegalArgumentException(name + " must be less or equal to " + ref + " (was: <" + parameter
320                     + ">)");
321         }
322     }
323 
324     /**
325      * Throws the {@link IllegalArgumentException} if the given <code>parameter</code> is not in the range specified
326      * by the <code>lowerBound</code> and <code>upperBound</code> values.
327      * 
328      * @param parameter
329      *            The parameter that has to be in the range specified by the <code>lowerBound</code> and
330      *            <code>upperBound</code> values.
331      * @param lowerBound
332      *            The lower bound of the interval the parameter is compared to
333      * @param upperBound
334      *            The upper bound of the interval the parameter is compared to
335      * @param name
336      *            The name of the parameter being checked
337      * @throws IllegalArgumentException
338      *             Thrown if the checked condition is not satisfied
339      */
340     public static void mustBeInRange(final double parameter, final double lowerBound, final double upperBound, final String name)
341             throws IllegalArgumentException {
342         if (parameter < lowerBound || parameter > upperBound) {
343             throw new IllegalArgumentException(name + " must be in range from " + lowerBound + " to " + upperBound
344                     + " (was: <" + parameter + ">)");
345         }
346     }
347 
348 }