001: /*
002: * The contents of this file are subject to the Mozilla Public License
003: * Version 1.1 (the "License"); you may not use this file except in
004: * compliance with the License. You may obtain a copy of the License at
005: * http://www.mozilla.org/MPL/
006: *
007: * Software distributed under the License is distributed on an "AS IS"
008: * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
009: * License for the specific language governing rights and limitations
010: * under the License.
011: *
012: * The Original Code is iSQL-Viewer, A Mutli-Platform Database Tool.
013: *
014: * The Initial Developer of the Original Code is iSQL-Viewer, A Mutli-Platform Database Tool.
015: * Portions created by Mark A. Kobold are Copyright (C) 2000-2007. All Rights Reserved.
016: *
017: * Contributor(s):
018: * Mark A. Kobold [mkobold <at> isqlviewer <dot> com].
019: *
020: * If you didn't download this code from the following link, you should check
021: * if you aren't using an obsolete version: http://www.isqlviewer.com
022: */
023: package org.isqlviewer.util;
024:
025: import java.util.Date;
026:
027: /**
028: * General utilities class for common data validation patterns and assertions.
029: * <p>
030: * Some of these methods are variations on the themes in JUnit however the exceptions thrown herein are more appropriate
031: * for runtime situations like {@link NullPointerException}, and {@link IllegalArgumentException}. Where as most
032: * applications are not actively catching an AssertionFailedError which can fall through an Exception trap.
033: * <p>
034: * The NULL_XXX constants defined within this class also help facilitate the usage of Object versions of primitive
035: * data-types, where normally primitives cannot be null, and typically a -1 or NaN would represent a null primitive.
036: * These object instances assist with code-readability when dealing with those types of situations.
037: *
038: * @author Mark A. Kobold
039: * @version 1.0
040: */
041: public final class Assertions {
042:
043: /**
044: * User constant for defining an null primitive long value.
045: * <p>
046: * <code>(Assertions.NULL_LONG.longValue() == -1) == true</code>
047: */
048: public static final Long NULL_LONG = new Long(-1);
049:
050: /**
051: * User constant for defining an null primitive integer value.
052: * <p>
053: * <code>(Assertions.NULL_INTEGER.intValue() == -1) == true</code>
054: */
055: public static final Integer NULL_INTEGER = new Integer(-1);
056:
057: /**
058: * User constant for defining an null primitive short value.
059: * <p>
060: * <code>(Assertions.NULL_SHORT.shortValue() == -1) == true</code>
061: */
062: public static final Short NULL_SHORT = new Short((short) -1);
063:
064: /**
065: * User constant for defining an null primitive byte value.
066: * <p>
067: * <code>(Assertions.NULL_BYTE.byteValue() == -1) == true</code>
068: */
069: public static final Byte NULL_BYTE = new Byte((byte) -1);
070:
071: /**
072: * User constant for defining an null primitive float value.
073: * <p>
074: * <code>Float.isNaN(Assertions.NULL_FLOAT) == true</code>
075: */
076: public static final Float NULL_FLOAT = new Float(Float.NaN);
077:
078: /**
079: * User constant for defining an null primitive double value.
080: * <p>
081: * <code>Double.isNaN(Assertions.NULL_DOUBLE) == true</code>
082: */
083: public static final Double NULL_DOUBLE = new Double(Double.NaN);
084:
085: /**
086: * User constant for defining an null primitive character value.
087: * <p>
088: * <code>(Assertions.NULL_CHARACTER.charValue() == 0) == true</code>
089: */
090: public static final Character NULL_CHARACTER = new Character(
091: (char) 0);
092:
093: /**
094: * User constant for defining an null primitive boolean value.
095: * <p>
096: * <code>Assertions.NULL_BOOLEAN.booleanValue() == false</code>
097: */
098: public static final Boolean NULL_BOOLEAN = Boolean.FALSE;
099:
100: /**
101: * User constant for defining an null date.
102: * <p>
103: * <code>(Assertions.NULL_DATE.getTime() == 0) == true</code>
104: * <p>
105: * Though this isn't a primitive type, it is effectively a wrapper for a long value,plus it is common data-type.
106: */
107: public static final Date NULL_DATE = new Date(0);
108:
109: private static final String RESOURCE_BUNDLE = "org.isqlviewer.util.ResourceBundle";
110: private static final LocalMessages messages = new LocalMessages(
111: RESOURCE_BUNDLE);
112:
113: private Assertions() {
114:
115: }
116:
117: /**
118: * Checks to ensure that the value is not less than zero.
119: * <p>
120: * Utility method for ensuring that the given value is positive otherwise throw an exception. This method version
121: * assumes no logical identifier with the given argument.
122: *
123: * @param value to check for positiveness.
124: * @throws IllegalArgumentException if the given value is less than zero.
125: * @throws NullPointerException if the given value is null.
126: */
127: public static void assertPositive(Number value) {
128:
129: assertPositive(null, value);
130: }
131:
132: /**
133: * Checks to ensure that the value is not less than zero.
134: * <p>
135: * Utility method for ensuring that the given value is positive otherwise throw an exception.
136: *
137: * @param identifier a logical name that will accompany the exception if generated; can be <tt>null</tt>.
138: * @param value to check for positiveness.
139: * @throws IllegalArgumentException if the given value is less than zero.
140: */
141: public static void assertPositive(String identifier, double value) {
142:
143: if (value < 0) {
144: String err = null;
145: if (identifier != null) {
146: err = messages.format(
147: "assertions.known_id_must_be_positive",
148: identifier, Double.toString(value));
149: } else {
150: err = messages.format(
151: "assertions.unknown_id_must_be_positive",
152: Double.toString(value));
153: }
154: throw new IllegalArgumentException(err);
155: }
156: }
157:
158: /**
159: * Checks to ensure that a Number value is not less than zero.
160: * <p>
161: * Utility method for ensuring that the given value is positive otherwise throw an exception.
162: *
163: * @param identifier a logical name that will accompany the exception if generated; can be <tt>null</tt>.
164: * @param value to check for positiveness.
165: * @throws IllegalArgumentException if the given value is less than zero.
166: * @throws NullPointerException if the given number value is null.
167: */
168: public static void assertPositive(String identifier, Number value) {
169:
170: assertNotNull(identifier, value);
171: assertPositive(value.doubleValue());
172: }
173:
174: /**
175: * Checks to ensure that the value is not less than zero.
176: * <p>
177: * Utility method for ensuring that the given value is positive otherwise throw an exception. This method version
178: * assumes no logical identifier with the given argument.
179: *
180: * @param value to check for positiveness.
181: * @throws IllegalArgumentException if the given value is less than zero.
182: */
183: public static void assertPositive(double value) {
184:
185: assertPositive(null, value);
186: }
187:
188: /**
189: * Checks to ensure that the value is not less than or equal zero.
190: * <p>
191: * Utility method for ensuring that the given value is positive excluding zero, otherwise throw an exception.
192: *
193: * @param value to check for positiveness.
194: * @throws IllegalArgumentException if the given value is less than or equal zero.
195: */
196: public static void assertPositiveExcludeZero(double value) {
197:
198: assertPositiveExcludeZero(null, value);
199: }
200:
201: /**
202: * Checks to ensure that the value is not less than or equal zero.
203: * <p>
204: * Utility method for ensuring that the given value is positive excluding zero, otherwise throw an exception.
205: *
206: * @param value to check for positiveness.
207: * @throws IllegalArgumentException if the given value is less than or equal zero.
208: */
209: public static void assertPositiveExcludeZero(Number value) {
210:
211: assertPositiveExcludeZero(null, value);
212: }
213:
214: /**
215: * Checks to ensure that the value is not less than or equal zero.
216: * <p>
217: * Utility method for ensuring that the given value is positive excluding zero, otherwise throw an exception.
218: *
219: * @param identifier a logical name that will accompany the exception if generated; can be <tt>null</tt>.
220: * @param value to check for positiveness.
221: * @throws IllegalArgumentException if the given value is less than or equal zero.
222: */
223: public static void assertPositiveExcludeZero(String identifier,
224: double value) {
225:
226: if (value <= 0) {
227: String err = null;
228: if (identifier != null) {
229: err = messages.format(
230: "assertions.known_id_must_be_positive",
231: identifier, Double.toString(value));
232: } else {
233: err = messages.format(
234: "assertions.unknown_id_must_be_positive",
235: Double.toString(value));
236: }
237: throw new IllegalArgumentException(err);
238: }
239: }
240:
241: /**
242: * Checks to ensure that the value is not less than or equal zero.
243: * <p>
244: * Utility method for ensuring that the given value is positive excluding zero, otherwise throw an exception.
245: *
246: * @param identifier a logical name that will accompany the exception if generated; can be <tt>null</tt>.
247: * @param value to check for positiveness.
248: * @throws IllegalArgumentException if the given value is less than or equal zero.
249: * @throws NullPointerException if the given number value is null.
250: */
251: public static void assertPositiveExcludeZero(String identifier,
252: Number value) {
253:
254: assertNotNull(identifier, value);
255: assertPositiveExcludeZero(identifier, value.doubleValue());
256: }
257:
258: /**
259: * Check to make sure that given value by name is not null.
260: * <p>
261: *
262: * @param identifier a logical name that will accompany the exception if generated; can be <tt>null</tt>.
263: * @param value to check for null.
264: * @throws NullPointerException if the given value is null.
265: */
266: public static void assertNotNull(String identifier, Object value) {
267:
268: if (value == null) {
269: String err = null;
270: if (identifier != null) {
271: err = messages.format(
272: "assertions.known_id_cannot_be_null",
273: identifier);
274: } else {
275: err = messages
276: .format("assertions.unknown_id_cannot_be_null");
277: }
278: throw new NullPointerException(err);
279: }
280: }
281:
282: /**
283: * Check to make sure that given value is not null.
284: * <p>
285: *
286: * @param value to check for null.
287: * @throws NullPointerException if the given value is null.
288: */
289: public static void assertNotNull(Object value) {
290:
291: assertNotNull(null, value);
292: }
293:
294: /**
295: * Check to make sure that given value by name is null.
296: * <p>
297: *
298: * @param identifier a logical name that will accompany the exception if generated; can be <tt>null</tt>.
299: * @param value to check for null.
300: * @throws IllegalArgumentException if the given value is not null.
301: */
302: public static void assertNull(String identifier, Object value) {
303:
304: if (value != null) {
305: String err = null;
306: if (identifier != null) {
307: err = messages.format(
308: "assertions.known_id_must_be_null", identifier);
309: } else {
310: err = messages
311: .format("assertions.unknown_id_must_be_null");
312: }
313: throw new IllegalArgumentException(err);
314: }
315: }
316:
317: /**
318: * Check to make sure that given value is null.
319: * <p>
320: *
321: * @param value to check for null.
322: * @throws IllegalArgumentException if the given value is not null.
323: */
324: public static void assertNull(Object value) {
325:
326: assertNull(null, value);
327: }
328:
329: /**
330: * Checks to ensure that the given value is less than or equal to given maximum value.
331: * <p>
332: *
333: * @param identifier a logical name that will accompany the exception if generated; can be <tt>null</tt>.
334: * @param value to assert that is less or equal to the maximum value.
335: * @param maximumValue that the given value is allowed to be.
336: * @throws IllegalArgumentException if the value is greater than the maximum value.
337: */
338: public static void assertLessThanEqual(String identifier,
339: double value, double maximumValue) {
340:
341: if (value > maximumValue) {
342: String err = null;
343: String maxString = Double.toString(maximumValue);
344: String valueString = Double.toString(value);
345: if (identifier != null) {
346: err = messages.format(
347: "assertions.known_id_value_too_large",
348: identifier, valueString, maxString);
349: } else {
350: err = messages.format(
351: "assertions.unknown_id_value_too_large",
352: valueString, maxString);
353: }
354: throw new IllegalArgumentException(err);
355: }
356: }
357:
358: /**
359: * Checks to ensure that the given value is less than or equal to given maximum value.
360: * <p>
361: *
362: * @param value to assert that is less or equal to the maximum value.
363: * @param maximumValue that the given value is allowed to be.
364: * @throws IllegalArgumentException if the value is greater than the maximum value.
365: */
366: public static void assertLessThanEqual(double value,
367: double maximumValue) {
368:
369: assertLessThanEqual(null, value, maximumValue);
370: }
371:
372: /**
373: * Checks to ensure that the given value is greater than or equal to minimum required value.
374: * <p>
375: *
376: * @param identifier a logical name that will accompany the exception if generated; can be <tt>null</tt>.
377: * @param value to assert that is less or equal to the maximum value.
378: * @param minimumValue the smallest value allowed.
379: * @throws IllegalArgumentException if the value is greater than the maximum value.
380: */
381: public static void assertGreaterThanEqual(String identifier,
382: double value, double minimumValue) {
383:
384: if (value < minimumValue) {
385: String err = null;
386: String minString = Double.toString(minimumValue);
387: String valueString = Double.toString(value);
388: if (identifier != null) {
389: err = messages.format(
390: "assertions.known_id_value_too_small",
391: identifier, valueString, minString);
392: } else {
393: err = messages.format(
394: "assertions.unknown_id_value_too_small",
395: valueString, minString);
396: }
397: throw new IllegalArgumentException(err);
398: }
399: }
400:
401: /**
402: * Checks to ensure that the given value is greater than or equal to minimum required value.
403: * <p>
404: *
405: * @param value to assert that is less or equal to the maximum value.
406: * @param minimumValue the smallest value allowed.
407: * @throws IllegalArgumentException if the value is greater than the maximum value.
408: */
409: public static void assertGreaterThanEqual(double value,
410: double minimumValue) {
411:
412: assertGreaterThanEqual(null, value, minimumValue);
413:
414: }
415:
416: /**
417: * Asserts that the expected value is equal to the actual value.
418: * <p>
419: *
420: * @param string identifier for this assertion; can be null.
421: * @param expected value of the actualValue variable.
422: * @param actualValue to verify against the expected value.
423: * @throws IllegalArgumentException if the values are not equal.
424: */
425: public static void assertEqual(String identifier, double expected,
426: double actualValue) {
427:
428: if (expected != actualValue) {
429: String err = null;
430: String expectation = Double.toString(expected);
431: String actual = Double.toString(actualValue);
432: if (identifier != null) {
433: err = messages.format(
434: "assertions.known_id_value_not_equal",
435: identifier, actual, expectation);
436: } else {
437: err = messages.format(
438: "assertions.unknown_id_value_not_equal",
439: actual, expectation);
440: }
441: throw new IllegalArgumentException(err);
442: }
443: }
444:
445: /**
446: * Asserts that the expected value is equal to the actual value.
447: * <p>
448: *
449: * @param expected value of the actualValue variable.
450: * @param actualValue to verify against the expected value.
451: * @throws IllegalArgumentException if the values are not equal.
452: */
453: public static void assertEqual(double expected, double actualValue) {
454:
455: assertEqual(null, expected, actualValue);
456: }
457: }
|