hirondelle.web4j.model
Class Check

Object
  hirondelle.web4j.model.Check

public class Check
extends Object

Returns commonly needed Validator objects.

In general, the number of possible validations is very large. It is not appropriate for a framework to attempt to implement all possible validations. Rather, a framework should provide the most common validations, and allow the application programmer to extend the validation mechanism as needed.

Validations are important parts of your program's logic. Using tools such as JUnit to test your validation code is highly recommended. Since your Model Objects have no dependencies on heavyweight objects, they're almost always easy to test.

If a specific validation is not provided here, other options include :

• performing the validation directly in the Model Object, without using Check or a Validator
• create a new Validator, and pass it to either required(Object, Validator...) or optional(Object, Validator...). This option is especially attractive when it will eliminate code repetition.
• subclassing this class, and adding new static methods

The range(long, long), min(long) and max(long) methods return Validators that perform checks on a long value. The source of the long value varies according to the type of Object passed to the Validator, and is taken as follows (int is internally converted to long when necessary) :

• Integer.intValue()
• Long.longValue()
• length of a trimmed String having content; the same is applied to Id.toString(), Code.getText(), and SafeText.getRawString().
• Collection.size()
• Map.size()
• Date.getTime() - underlying millisecond value
• Calendar.getTimeInMillis() - underlying millisecond value
• any other class will cause an exception to be thrown by min(long) and max(long)

The required(Object), required(Object, Validator...) and optional(Object, Validator...) methods are important, and are separated out as distinct validations. In addition, the required/optional character of a field is always the first validation performed (see examples below).

In general, it is highly recommended that applications aggressively perform all possible validations.

Note that when validation is performed in a Model Object, then it will apply both to objects created from user input, and to objects created from a database ResultSet.

Example 1
Example of a required field in a Model Object (that is, the field is of any type, and must be non-null) :

if ( ! Check.required(fStartDate) ) {
  ex.add("Start Date is Required.");
}
 

Example 2
Example of a required text field, which must have visible content (as in Util.textHasContent(String)) :

if ( ! Check.required(fTitle) ) {
  ex.add("Title is required, and must have content.");
}
 

Example 3
Example of a required text field, whose length must be in the range 2..50 :

if ( ! Check.required(fTitle, Check.range(2,50)) ) {
  ex.add("Title is required, and must have between 2 and 50 characters.");
}
 

Example 4
Example of an optional String field that matches the format '1234-5678' :

//compile the pattern once, when the class is loaded
private static final Pattern fID_PATTERN = Pattern.compile("(\\d){4}-(\\d){4}");
...
if ( ! Check.optional(fSomeId, Check.pattern(fID_PATTERN)) ) {
  ex.add("Id is optional, and must have the form '1234-5678'.");
}
 

Example 5
The initial ! negation operator is easy to forget. Many will prefer a more explicit style, which seems to be more legible :

import static hirondelle.web4j.util.Consts.FAILS;
...
if ( FAILS == Check.required(fStartDate) ) {
  ex.add("Start Date is Required.");
}
 

Here is one style for implementing custom validations for your application :

//Checks that a person's age is in the range 0..150
public static Validator ageRange(){
  class CheckAge implements Validator {
    public boolean isValid(Object aObject) {
      Integer age = (Integer)aObject;
      return 0 <= age <= 150; 
    }
  }
  return new CheckAge();
}
 

Constructor Summary

protected

Check() This no-argument constructor is empty.

Method Summary

static Validator	email() Return a Validator to verify a String or SafeText field is a syntactically valid email address.
static Validator	forSpam() Return a Validator to check that a String or SafeText field is not spam, according to SpamDetector.
static Validator	isFalse(Boolean... aPredicates) Return a Validator to check that all passed booleans are false.
static Validator	isTrue(Boolean... aPredicates) Return a Validator to check that all passed booleans are true.
static Validator	max(BigDecimal aMaximumValue) Return a Validator to check that a BigDecimal field is less than or equal to aMaximumValue.
static Validator	max(DateTime aMaximumValue) Return a Validator to check that a DateTime is less than or equal to aMaximumValue.
static Validator	max(Decimal aMaximumValue) Return a Validator to check that a Decimal amount is less than or equal to aMaximumValue.
static Validator	max(long aMaximumValue) Return a Validator to check that a field's value is less than or equal to aMaximumValue.
static Validator	min(BigDecimal aMinimumValue) Return a Validator to check that a BigDecimal field is greater than or equal to aMinimumValue.
static Validator	min(DateTime aMinimumValue) Return a Validator to check that a DateTime is greater than or equal to aMinimumValue.
static Validator	min(Decimal aMinimumValue) Return a Validator to check that a Decimal amount is greater than or equal to aMinimumValue.
static Validator	min(long aMinimumValue) Return a Validator to check that a field's value is greater than or equal to aMinimumValue.
static Validator	numDecimalsAlways(int aNumDecimals) Return a Validator to check that the number of decimal places of a Decimal or BigDecimal is exactly equal to aNumDecimals.
static Validator	numDecimalsMax(int aMaxNumberOfDecimalPlaces) Return a Validator to check that the number of decimal places of a Decimal or BigDecimal is less than or equal to aMaxNumberOfDecimalPlaces.
static boolean	optional(Object aObject, Validator... aValidators) Return true only if aObject is null, OR if aObject is non-null and passes all validations.
static Validator	pattern(Pattern aRegex) Return a Validator that checks a String or SafeText field versus a regular expression Pattern.
static Validator	range(BigDecimal aMinimumValue, BigDecimal aMaximumValue) Return a Validator to check that a BigDecimal value is in a certain range (inclusive).
static Validator	range(DateTime aMinimumValue, DateTime aMaximumValue) Return a Validator to check that a DateTime is in a certain range (inclusive).
static Validator	range(Decimal aMinimumValue, Decimal aMaximumValue) Return a Validator to check that a Decimal amount is in a certain range (inclusive).
static Validator	range(long aMinimumValue, long aMaximumValue) Return a Validator to check that a field's value is in a certain range (inclusive).
static boolean	required(Object aObject) Return true only if aObject is non-null.
static boolean	required(Object aObject, Validator... aValidators) Return true only if aObject satisfies required(Object), and it passes all given validations

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Check

protected Check()

This no-argument constructor is empty.

This constructor exists only because of it has protected scope. Having protected scope has two desirable effects:

• typical callers cannot create Check objects. This is appropriate since this class contains only static methods.
• if needed, this class may be subclassed. This is useful when you need to add custom validations.

Method Detail

required

public static boolean required(Object aObject)

Return true only if aObject is non-null.

String and SafeText objects are a special case : instead of just being non-null, they must have content according to Util.textHasContent(String).

Parameters:

aObject - possibly-null field of a Model Object.

required

public static boolean required(Object aObject,
                               Validator... aValidators)

Return true only if aObject satisfies required(Object), and it passes all given validations

Parameters:

aObject - possibly-null field of a Model Object.

optional

public static boolean optional(Object aObject,
                               Validator... aValidators)

Return true only if aObject is null, OR if aObject is non-null and passes all validations.

String and SafeText objects are a special case : instead of just being non-null, they must have content according to Util.textHasContent(String).

Parameters:

aObject - possibly-null field of a Model Object.

isTrue

public static Validator isTrue(Boolean... aPredicates)

Return a Validator to check that all passed booleans are true. Note that the single parameter is a sequence parameter, so you may pass in many booleans, not just one.

This is a bizarre method, but it's actually useful. It allows checks on an object's state to be treated as any other check.

isFalse

public static Validator isFalse(Boolean... aPredicates)

Return a Validator to check that all passed booleans are false. Note that the single parameter is a sequence parameter, so you may pass in many booleans, not just one.

This is a bizarre method, but it's actually useful. It allows checks on an object's state to be treated as any other check.

min

public static Validator min(long aMinimumValue)

Return a Validator to check that a field's value is greater than or equal to aMinimumValue. See class comment for the kind of objects which may be checked by the returned Validator.

min

public static Validator min(BigDecimal aMinimumValue)

Return a Validator to check that a BigDecimal field is greater than or equal to aMinimumValue.

min

public static Validator min(Decimal aMinimumValue)

Return a Validator to check that a Decimal amount is greater than or equal to aMinimumValue. This methods allows comparisons between Money objects of different currency.

min

public static Validator min(DateTime aMinimumValue)

Return a Validator to check that a DateTime is greater than or equal to aMinimumValue.

max

public static Validator max(long aMaximumValue)

Return a Validator to check that a field's value is less than or equal to aMaximumValue. See class comment for the kind of objects which may be checked by the returned Validator.

max

public static Validator max(BigDecimal aMaximumValue)

Return a Validator to check that a BigDecimal field is less than or equal to aMaximumValue.

max

public static Validator max(Decimal aMaximumValue)

Return a Validator to check that a Decimal amount is less than or equal to aMaximumValue. This methods allows comparisons between Money objects of different currency.

max

public static Validator max(DateTime aMaximumValue)

Return a Validator to check that a DateTime is less than or equal to aMaximumValue.

range

public static Validator range(long aMinimumValue,
                              long aMaximumValue)

Return a Validator to check that a field's value is in a certain range (inclusive). See class comment for the kind of objects which may be checked by the returned Validator.

range

public static Validator range(BigDecimal aMinimumValue,
                              BigDecimal aMaximumValue)

Return a Validator to check that a BigDecimal value is in a certain range (inclusive).

range

public static Validator range(Decimal aMinimumValue,
                              Decimal aMaximumValue)

Return a Validator to check that a Decimal amount is in a certain range (inclusive). This methods allows comparisons between Money objects of different currency.

range

public static Validator range(DateTime aMinimumValue,
                              DateTime aMaximumValue)

Return a Validator to check that a DateTime is in a certain range (inclusive).

numDecimalsMax

public static Validator numDecimalsMax(int aMaxNumberOfDecimalPlaces)

Return a Validator to check that the number of decimal places of a Decimal or BigDecimal is less than or equal to aMaxNumberOfDecimalPlaces.

Parameters:

aMaxNumberOfDecimalPlaces - is greater than or equal to 1.

numDecimalsAlways

public static Validator numDecimalsAlways(int aNumDecimals)

Return a Validator to check that the number of decimal places of a Decimal or BigDecimal is exactly equal to aNumDecimals.

Parameters:

aNumDecimals - is 0 or more.

pattern

public static Validator pattern(Pattern aRegex)

Return a Validator that checks a String or SafeText field versus a regular expression Pattern.

This method might be used to validate a zip code, phone number, and so on - any text which has a well defined format.

There must be a complete match versus the whole text, as in Matcher.matches(). In addition, the returned Validator will not trim the text before performing the validation.

Parameters:

aRegex - is a Pattern, which holds a regular expression.

email

public static Validator email()

Return a Validator to verify a String or SafeText field is a syntactically valid email address.

See WebUtil.isValidEmailAddress(String). The text is not trimmed by the returned Validator.

forSpam

public static Validator forSpam()

Return a Validator to check that a String or SafeText field is not spam, according to SpamDetector.