web4j: comparison classes/hirondelle/web4j/model/Check.java

equal deleted inserted replaced

--1:000000000000
+:3060119b1292
+package hirondelle.web4j.model;
+import java.util.*;
+import java.util.logging.Logger;
+import java.util.regex.*;
+import java.math.BigDecimal;
+import hirondelle.web4j.BuildImpl;
+import hirondelle.web4j.security.SafeText;
+import hirondelle.web4j.security.SpamDetector;
+import hirondelle.web4j.util.Util;
+import hirondelle.web4j.util.WebUtil;
+import static hirondelle.web4j.util.Consts.PASSES;
+import static hirondelle.web4j.util.Consts.FAILS;
+import hirondelle.web4j.util.Args;
+/**
+<span class="highlight">Returns commonly needed {@link Validator} objects.</span>
+<P>In general, the number of possible validations is <em>very</em> large. It is not appropriate
+for a framework to attempt to implement <em>all</em> possible validations. Rather, a framework should
+provide the most common validations, and allow the application programmer to extend
+the validation mechanism as needed.
+<P>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.
+<P>If a specific validation is not provided here, other options include :
+<ul>
+<li>performing the validation directly in the Model Object, without using <tt>Check</tt> or
+a {@link Validator}
+<li>create a new {@link Validator}, and pass it to either {@link #required(Object, Validator...)}
+or {@link #optional(Object, Validator...)}. This option is especially attractive when it will eliminate
+code repetition.
+<li>subclassing this class, and adding new <tt>static</tt> methods
+</ul>
+<P>The {@link #range(long, long)}, {@link #min(long)} and {@link #max(long)} methods return {@link Validator}s
+that perform checks on a <tt>long</tt> value. <span class='highlight'>The <em>source</em> of the <tt>long</tt> value varies
+according to the type of <tt>Object</tt> passed to the {@link Validator}</span>, and is taken as follows
+(<tt>int</tt> is internally converted to <tt>long</tt> when necessary) :
+<ul>
+<li>{@link Integer#intValue()}
+<li>{@link Long#longValue()}
+<li>length of a trimmed {@link String} having content; the same is applied to {@link Id#toString()},
+{@link Code#getText()}, and {@link SafeText#getRawString()}.
+<li>{@link Collection#size()}
+<li>{@link Map#size()}
+<li>{@link Date#getTime()} - underlying millisecond value
+<li>{@link Calendar#getTimeInMillis()} - underlying millisecond value
+<li>any other class will cause an exception to be thrown by {@link #min(long)} and {@link #max(long)}
+</ul>
+<P>The {@link #required(Object)}, {@link #required(Object, Validator...)} and {@link #optional(Object, Validator...)}
+methods are important, and are separated out as distinct validations. <span class='highlight'>In addition, the
+required/optional character of a field is always the <em>first</em> validation performed</span> (see examples below).
+<P><span class="highlight">In general, it is highly recommended that applications
+aggressively perform all possible validations.</span>
+<P> 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 <tt>ResultSet</tt>.
+<P><b>Example 1</b><br>
+Example of a required field in a Model Object (that is, the field is of any type, and
+must be non-<tt>null</tt>) :
+<PRE>
+if ( ! Check.required(fStartDate) ) {
+ex.add("Start Date is Required.");
+}
+</PRE>
+<P><b>Example 2</b><br>
+Example of a required <em>text</em> field, which must have visible content
+(as in {@link Util#textHasContent(String)}) :
+<PRE>
+if ( ! Check.required(fTitle) ) {
+ex.add("Title is required, and must have content.");
+}
+</PRE>
+<P><b>Example 3</b><br>
+Example of a required text field, whose length must be in the range <tt>2..50</tt> :
+<PRE>
+if ( ! Check.required(fTitle, Check.range(2,50)) ) {
+ex.add("Title is required, and must have between 2 and 50 characters.");
+}
+</PRE>
+<P><b>Example 4</b><br>
+Example of an optional <tt>String</tt> field that matches the format '<tt>1234-5678</tt>' :
+<PRE>
+//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'.");
+}
+</PRE>
+<P><b>Example 5</b><br>
+The initial <tt>!</tt> negation operator is easy to forget. Many will prefer a more explicit style, which seems
+to be more legible :
+<PRE>
+import static hirondelle.web4j.util.Consts.FAILS;
+...
+if ( FAILS == Check.required(fStartDate) ) {
+ex.add("Start Date is Required.");
+}
+</PRE>
+<P>Here is one style for implementing custom validations for your application :
+<PRE>
+//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();
+}
+</PRE>
+*/
+public class Check {
+/**
+Return <tt>true</tt> only if <tt>aObject</tt> is non-<tt>null</tt>.
+<P><em><tt>String</tt> and {@link SafeText} objects are a special case</em> : instead of just
+being non-<tt>null</tt>, they must have content according to {@link Util#textHasContent(String)}.
+@param aObject possibly-null field of a Model Object.
+*/
+public static boolean required(Object aObject){
+boolean result = FAILS;
+if ( isText(aObject) ) {
+result = Util.textHasContent(getText(aObject));
+}
+else {
+result = (aObject != null);
+}
+return result;
+}
+/**
+Return <tt>true</tt> only if <tt>aObject</tt> satisfies {@link #required(Object)},
+<em>and</em> it passes all given validations
+@param aObject possibly-null field of a Model Object.
+*/
+public static boolean required(Object aObject, Validator... aValidators){
+boolean result = PASSES;
+if ( ! required(aObject) ) {
+result = FAILS;
+}
+else {
+result = passesValidations(aObject, aValidators);
+}
+return result;
+}
+/**
+Return <tt>true</tt> only if <tt>aObject</tt> is <tt>null</tt>, OR if <tt>aObject</tt> is non-<tt>null</tt>
+and passes all validations.
+<P><em><tt>String</tt> and {@link SafeText} objects are a special case</em> : instead of just
+being non-<tt>null</tt>, they must have content according to {@link Util#textHasContent(String)}.
+@param aObject possibly-null field of a Model Object.
+*/
+public static boolean optional(Object aObject, Validator... aValidators){
+boolean result = PASSES;
+if ( aObject != null ){
+if( isText(aObject) ) {
+result = Util.textHasContent(getText(aObject)) && passesValidations(aObject, aValidators);
+}
+else {
+result = passesValidations(aObject, aValidators);
+}
+}
+return result;
+}
+/**
+Return a {@link Validator} to check that all passed booleans are <tt>true</tt>.
+Note that the single parameter is a sequence parameter, so you may pass in many booleans, not just one.
+<P>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.
+*/
+public static Validator isTrue(Boolean... aPredicates){
+class AllTrue implements Validator{
+AllTrue(Boolean... aPreds){
+fPredicates = aPreds;
+}
+public boolean isValid(Object aObject) {
+//aObject is ignored here
+boolean result = true;
+for (Boolean predicate: fPredicates){
+result = result && predicate;
+}
+return result;
+};
+private Boolean[] fPredicates;
+}
+return new AllTrue(aPredicates);
+}
+/**
+Return a {@link Validator} to check that all passed booleans are <tt>false</tt>.
+Note that the single parameter is a sequence parameter, so you may pass in many booleans, not just one.
+<P>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.
+*/
+public static Validator isFalse(Boolean... aPredicates){
+class AllFalse implements Validator{
+AllFalse(Boolean... aPreds){
+fPredicates = aPreds;
+}
+public boolean isValid(Object aObject) {
+//aObject is ignored here
+boolean result = true;
+for (Boolean predicate: fPredicates){
+result = result && !predicate;
+}
+return result;
+};
+private Boolean[] fPredicates;
+}
+return new AllFalse(aPredicates);
+}
+/**
+Return a {@link Validator} to check that a field's value is greater than or equal to <tt>aMinimumValue</tt>.
+See class comment for the kind of objects which may be checked by the returned {@link Validator}.
+*/
+public static Validator min(final long aMinimumValue){
+class Minimum implements Validator {
+Minimum(long aMinValue){
+fMinValue = aMinValue;
+}
+public boolean isValid(Object aObject){
+long value = getValueAsLong(aObject);
+return value >= fMinValue;
+}
+private final long fMinValue;
+}
+return new Minimum(aMinimumValue);
+}
+/**
+Return a {@link Validator} to check that a {@link BigDecimal} field is greater than or equal
+to <tt>aMinimumValue</tt>.
+*/
+public static Validator min(final BigDecimal aMinimumValue){
+class Minimum implements Validator {
+Minimum(BigDecimal aMinValue){
+fMinValue = aMinValue;
+}
+public boolean isValid(Object aObject){
+BigDecimal value = (BigDecimal)aObject;
+return value.compareTo(fMinValue) >= 0;
+}
+private final BigDecimal fMinValue;
+}
+return new Minimum(aMinimumValue);
+}
+/**
+Return a {@link Validator} to check that a {@link Decimal} amount is greater than or equal
+to <tt>aMinimumValue</tt>. This methods allows comparisons between
+<tt>Money</tt> objects of different currency.
+*/
+public static Validator min(final Decimal aMinimumValue){
+class Minimum implements Validator {
+Minimum(Decimal aMinValue){
+fMinValue = aMinValue;
+}
+public boolean isValid(Object aObject){
+Decimal value = (Decimal)aObject;
+return value.gteq(fMinValue);
+}
+private final Decimal fMinValue;
+}
+return new Minimum(aMinimumValue);
+}
+/**
+Return a {@link Validator} to check that a {@link DateTime} is greater than or equal
+to <tt>aMinimumValue</tt>.
+*/
+public static Validator min(final DateTime aMinimumValue){
+class Minimum implements Validator {
+Minimum(DateTime aMinValue){
+fMinValue = aMinValue;
+}
+public boolean isValid(Object aObject){
+DateTime value = (DateTime)aObject;
+return value.gteq(fMinValue);
+}
+private final DateTime fMinValue;
+}
+return new Minimum(aMinimumValue);
+}
+/**
+Return a {@link Validator} to check that a field's value is less than or equal to <tt>aMaximumValue</tt>.
+See class comment for the kind of objects which may be checked by the returned {@link Validator}.
+*/
+public static Validator max(final long aMaximumValue){
+class Maximum implements Validator {
+Maximum(long aMaxValue){
+fMaxValue = aMaxValue;
+}
+public boolean isValid(Object aObject){
+long value = getValueAsLong(aObject);
+return value <= fMaxValue;
+}
+private final long fMaxValue;
+}
+return new Maximum(aMaximumValue);
+}
+/**
+Return a {@link Validator} to check that a {@link BigDecimal} field is less than or equal
+to <tt>aMaximumValue</tt>.
+*/
+public static Validator max(final BigDecimal aMaximumValue){
+class Maximum implements Validator {
+Maximum(BigDecimal aMaxValue){
+fMaxValue = aMaxValue;
+}
+public boolean isValid(Object aObject){
+BigDecimal value = (BigDecimal)aObject;
+return value.compareTo(fMaxValue) <= 0;
+}
+private final BigDecimal fMaxValue;
+}
+return new Maximum(aMaximumValue);
+}
+/**
+Return a {@link Validator} to check that a {@link Decimal} amount is less than or equal
+to <tt>aMaximumValue</tt>. This methods allows comparisons between
+<tt>Money</tt> objects of different currency.
+*/
+public static Validator max(final Decimal aMaximumValue){
+class Maximum implements Validator {
+Maximum(Decimal aMaxValue){
+fMaxValue = aMaxValue;
+}
+public boolean isValid(Object aObject){
+Decimal value = (Decimal)aObject;
+return value.lteq(fMaxValue);
+}
+private final Decimal fMaxValue;
+}
+return new Maximum(aMaximumValue);
+}
+/**
+Return a {@link Validator} to check that a {@link DateTime} is less than or equal
+to <tt>aMaximumValue</tt>.
+*/
+public static Validator max(final DateTime aMaximumValue){
+class Maximum implements Validator {
+Maximum(DateTime aMaxValue){
+fMaxValue = aMaxValue;
+}
+public boolean isValid(Object aObject){
+DateTime value = (DateTime)aObject;
+return value.lteq(fMaxValue);
+}
+private final DateTime fMaxValue;
+}
+return new Maximum(aMaximumValue);
+}
+/**
+Return a {@link 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 {@link Validator}.
+*/
+public static Validator range(final long aMinimumValue, final long aMaximumValue){
+class Range implements Validator {
+Range(long aMin, long aMax){
+fMinValue = aMin;
+fMaxValue = aMax;
+}
+public boolean isValid(Object aObject){
+long value = getValueAsLong(aObject);
+return fMinValue <= value && value <= fMaxValue;
+}
+private final long fMinValue;
+private final long fMaxValue;
+}
+return new Range(aMinimumValue, aMaximumValue);
+}
+/**
+Return a {@link Validator} to check that a {@link BigDecimal} value is in a certain range (inclusive).
+*/
+public static Validator range(final BigDecimal aMinimumValue, final BigDecimal aMaximumValue){
+class Range implements Validator {
+Range(BigDecimal aMin, BigDecimal aMax){
+fMinValue = aMin;
+fMaxValue = aMax;
+}
+public boolean isValid(Object aObject){
+BigDecimal value = (BigDecimal)aObject;
+return value.compareTo(fMinValue) >= 0 && value.compareTo(fMaxValue) <= 0;
+}
+private final BigDecimal fMinValue;
+private final BigDecimal fMaxValue;
+}
+return new Range(aMinimumValue, aMaximumValue);
+}
+/**
+Return a {@link Validator} to check that a {@link Decimal} amount is in a certain range (inclusive).
+This methods allows comparisons between <tt>Money</tt> objects of different currency.
+*/
+public static Validator range(final Decimal aMinimumValue, final Decimal aMaximumValue){
+class Range implements Validator {
+Range(Decimal aMin, Decimal aMax){
+fMinValue = aMin;
+fMaxValue = aMax;
+}
+public boolean isValid(Object aObject){
+Decimal value = (Decimal)aObject;
+return value.gteq(fMinValue) && value.lteq(fMaxValue);
+}
+private final Decimal fMinValue;
+private final Decimal fMaxValue;
+}
+return new Range(aMinimumValue, aMaximumValue);
+}
+/**
+Return a {@link Validator} to check that a {@link DateTime} is in a certain range (inclusive).
+*/
+public static Validator range(final DateTime aMinimumValue, final DateTime aMaximumValue){
+class Range implements Validator {
+Range(DateTime aMin, DateTime aMax){
+fMinValue = aMin;
+fMaxValue = aMax;
+}
+public boolean isValid(Object aObject){
+DateTime value = (DateTime)aObject;
+boolean isInRange = value.gt(fMinValue) && value.lt(fMaxValue);
+boolean isAtAnEndpoint = value.equals(fMinValue) || value.equals(fMaxValue);
+return isInRange || isAtAnEndpoint;
+}
+private final DateTime fMinValue;
+private final DateTime fMaxValue;
+}
+return new Range(aMinimumValue, aMaximumValue);
+}
+/**
+Return a {@link Validator} to check that the number of decimal places of a {@link Decimal} or
+{@link BigDecimal} is <em>less than or equal to</em> <tt>aMaxNumberOfDecimalPlaces</tt>.
+@param aMaxNumberOfDecimalPlaces is greater than or equal to <tt>1</tt>.
+*/
+public static Validator numDecimalsMax(final int aMaxNumberOfDecimalPlaces){
+Args.checkForPositive(aMaxNumberOfDecimalPlaces);
+class MaxNumPlaces implements Validator {
+MaxNumPlaces(int aMaxNumberOfDecimals){
+Args.checkForPositive(aMaxNumberOfDecimals);
+fMaxNumPlaces = aMaxNumberOfDecimals;
+}
+public boolean isValid(Object aObject){
+return Util.hasMaxDecimals(extractNumber(aObject), fMaxNumPlaces);
+}
+private final int fMaxNumPlaces;
+}
+return new MaxNumPlaces(aMaxNumberOfDecimalPlaces);
+}
+/**
+Return a {@link Validator} to check that the number of decimal places of a {@link Decimal}
+or {@link BigDecimal} is <em>exactly equal to</em> <tt>aNumDecimals</tt>.
+@param aNumDecimals is 0 or more.
+*/
+public static Validator numDecimalsAlways(final int aNumDecimals){
+class NumPlaces implements Validator {
+NumPlaces(int aNumberOfDecimalPlaces){
+fNumPlaces = aNumberOfDecimalPlaces;
+}
+public boolean isValid(Object aObject){
+return Util.hasNumDecimals(extractNumber(aObject), fNumPlaces);
+}
+private final int fNumPlaces;
+}
+return new NumPlaces(aNumDecimals);
+}
+/**
+Return a {@link Validator} that checks a {@link String} or {@link SafeText}
+field versus a regular expression {@link Pattern}.
+<P>This method might be used to validate a zip code, phone number, and so on - any text which has a
+well defined format.
+<P>There must be a complete match versus the whole text, as in {@link Matcher#matches()}.
+In addition, the returned {@link Validator} will not trim the text before performing the validation.
+@param aRegex is a {@link Pattern}, which holds a regular expression.
+*/
+public static Validator pattern(final Pattern aRegex){
+class PatternValidator implements Validator {
+PatternValidator(Pattern aSomeRegex){
+fRegex = aSomeRegex;
+}
+public boolean isValid(Object aObject) {
+Matcher matcher = fRegex.matcher(getText(aObject));
+return matcher.matches();
+}
+private final Pattern fRegex;
+}
+return new PatternValidator(aRegex);
+}
+/**
+Return a {@link Validator} to verify a {@link String} or {@link SafeText} field is a syntactically
+valid email address.
+<P>See {@link WebUtil#isValidEmailAddress(String)}. The text is not trimmed by the returned
+{@link Validator}.
+*/
+public static Validator email(){
+class EmailValidator implements Validator {
+public boolean isValid(Object aObject) {
+return WebUtil.isValidEmailAddress(getText(aObject));
+}
+}
+return new EmailValidator();
+}
+/**
+Return a {@link Validator} to check that a {@link String} or {@link SafeText} field is not spam,
+according to {@link SpamDetector}.
+*/
+public static Validator forSpam(){
+class SpamValidator implements Validator {
+public boolean isValid(Object aObject) {
+SpamDetector spamDetector = BuildImpl.forSpamDetector();
+return !spamDetector.isSpam(getText(aObject));
+}
+}
+return new SpamValidator();
+}
+/*
+Note : forURL() method was attempted, but abandoned.
+The JDK implementation of the URL constructor seems very flaky.
+*/
+/**
+This no-argument constructor is empty.
+<P>This constructor exists only because of it has <tt>protected</tt> scope.
+Having <tt>protected</tt> scope has two desirable effects:
+<ul>
+<li>typical callers cannot create <tt>Check</tt> objects. This is appropriate since this class contains
+only static methods.
+<li>if needed, this class may be subclassed. This is useful when you need to add custom validations.
+</ul>
+*/
+protected Check(){
+//empty - prevent construction by caller, but allow it for subclasses
+}
+// PRIVATE //
+private static final Logger fLogger = Util.getLogger(Check.class);
+private static boolean passesValidations(Object aObject, Validator... aValidators) {
+boolean result = PASSES;
+for(Validator validator: aValidators){
+if ( ! validator.isValid(aObject) ) {
+result = FAILS;
+fLogger.fine("Failed a validation.");
+break;
+}
+}
+return result;
+}
+private static long getValueAsLong(Object aObject){
+long result = 0;
+if ( aObject instanceof Integer){
+Integer value = (Integer)aObject;
+result = value.intValue();
+}
+else if (aObject instanceof Long) {
+Long value = (Long)aObject;
+result = value.longValue();
+}
+else if (aObject instanceof String){
+String text = (String)aObject;
+if ( Util.textHasContent(text) ) {
+result = text.trim().length();
+}
+}
+else if (aObject instanceof Id){
+Id id = (Id)aObject;
+if ( Util.textHasContent(id.toString()) ) {
+result = id.toString().trim().length();
+}
+}
+else if (aObject instanceof SafeText){
+SafeText text = (SafeText)aObject;
+if ( Util.textHasContent(text.getRawString()) ) {
+result = text.getRawString().trim().length();
+}
+}
+else if (aObject instanceof Code){
+Code code = (Code)aObject;
+if ( Util.textHasContent(code.getText()) ) {
+result = code.getText().getRawString().trim().length();
+}
+}
+else if (aObject instanceof Collection) {
+Collection collection = (Collection)aObject;
+result = collection.size();
+}
+else if (aObject instanceof Map) {
+Map map = (Map)aObject;
+result = map.size();
+}
+else if (aObject instanceof Date) {
+Date date = (Date)aObject;
+result = date.getTime();
+}
+else if (aObject instanceof Calendar){
+Calendar calendar = (Calendar)aObject;
+result = calendar.getTimeInMillis();
+}
+else {
+String message = "Unexpected type of Object: " + aObject.getClass().getName();
+fLogger.severe(message);
+throw new AssertionError(message);
+}
+return result;
+}
+private static boolean isText(Object aObject){
+return (aObject instanceof String) || (aObject instanceof SafeText);
+}
+private static String getText(Object aObject){
+String result = null;
+if ( aObject instanceof String ){
+String text = (String) aObject;
+result = text.toString();
+}
+else if (aObject instanceof SafeText ){
+SafeText text = (SafeText)aObject;
+result = text.getRawString();
+}
+return result;
+}
+/** aObject must be a BigDecimal or a Money object.  */
+private static BigDecimal extractNumber(Object aObject){
+BigDecimal result = null;
+if( aObject instanceof BigDecimal){
+result = (BigDecimal)aObject;
+}
+else if (aObject instanceof Decimal) {
+Decimal decimal = (Decimal)aObject;
+result = decimal.getAmount();
+}
+else {
+throw new IllegalArgumentException("Unexpected class: " + aObject.getClass());
+}
+return result;
+}
+}