echopoint.validation
Interface ValidationRule

All Superinterfaces:

java.io.Serializable

All Known Implementing Classes:

SimpleRule

public interface ValidationRule
extends java.io.Serializable

A ValidationRule is a validation rule that can be run on the client side, via getJsRule(), or run on the server side via isValid(), and has an associated error message if it found to be invalid.

Field Summary

static int	RUN_ON_BLUR Used to indicate that a rule is to run when the user leaves a field
static int	RUN_ON_SUBMIT Used to indicate that a rule is to run when the user submits data

Method Summary

java.lang.String	getErrorMessage(Validateable validateable, java.lang.String fieldName) Returns the error message that can be used if the rule fails validation.
java.lang.String	getJS(Validateable validateable, int runOption) This returns a JavaScript expression that can be used to validate the rule on the client.
java.lang.String	getJSErrorMessage(Validateable validateable, java.lang.String fieldName) Returns the error message that can be used if the rule fails client side JavScript validation.
boolean	isValid(Validateable validateable) This returns true if the Validateable is in fact valid.

Field Detail

RUN_ON_BLUR

static final int RUN_ON_BLUR

Used to indicate that a rule is to run when the user leaves a field

See Also:

Constant Field Values

RUN_ON_SUBMIT

static final int RUN_ON_SUBMIT

Used to indicate that a rule is to run when the user submits data

See Also:

Constant Field Values

Method Detail

getErrorMessage

java.lang.String getErrorMessage(Validateable validateable,
                                 java.lang.String fieldName)

Returns the error message that can be used if the rule fails validation. The Locale within the Validateable can be used to localise the error message.

Parameters:

validateable - - the Validateable in play

fieldName - - the field name of the Validateable

Returns:

- a error message string

getJSErrorMessage

java.lang.String getJSErrorMessage(Validateable validateable,
                                   java.lang.String fieldName)

Returns the error message that can be used if the rule fails client side JavScript validation. The Locale within the Validateable can be used to localise the error message.

If this returns null, then the getErrorMessage() method may be called to retrieve an error message.

Parameters:

validateable - - the Validateable in play

fieldName - - the field name of the Validateable

Returns:

- a error message string

getJS

java.lang.String getJS(Validateable validateable,
                       int runOption)

This returns a JavaScript expression that can be used to validate the rule on the client. The expression must evaluate to true if the rule is to be considered valid.

The runOption parameter is used to control what rules is returned for which client event, field blur or server submit. This allows you to fine tune when rules are run. In general you probably want them to run on both field blur and server submit.

If you return null, then no rule will be run.

Two JS variables will be available into the expression. The first is called "value" which is the string value to be validated. The other is called "element", which is the HTML elment that is being validated.

The pre-built functions available inside the rules are listed below :

isIntegerStrict(value)

Returns true if the value is an positive Integer value.

Example :

 isIntegerStrict('123') == true
 isIntegerStrict(' 123 ') == false
 
 

isInteger(value)

Returns the same as isIntegerStrict() except white-space is trimmed first.

Example :

 isIntegerStrict('123') == true
 isIntegerStrict(' 123 ') == true
 isIntegerStrict(' 123a ') == false
 
 

isSignedIntegerStrict(value)

Returns true if the value is an positive or negative Integer value

Example :

 isSignedIntegerStrict('123') == true
 isSignedIntegerStrict('-123') == true
 isSignedIntegerStrict('+123 ') == false
 isSignedIntegerStrict('123+') == false
 
 

isSignedInteger(value)

Returns the same as isSignedIntegerStrict() except white-space is trimmed first

Example :

 isSignedInteger('123') == true
 isSignedInteger('-123') == true
 isSignedInteger('+123 ') == true
 isSignedInteger('123+') == false
 
 

isDecimalStrict(value)

Returns true if the value is an positive Decimal value

Example :

 isDecimalStrict('123') == true
 isDecimalStrict('123.23') == true
 isDecimalStrict('123.23 ') == false
 isDecimalStrict('+123.34') == false
 
 

isDecimal(value)

Returns the same as isDecimalStrict() except white-space is trimmed first

Example :

 isDecimal('123') == true
 isDecimal('123.23') == true
 isDecimal('123.23 ') == true
 isDecimal('+123.34') == false
 
 

isSignedDecimalStrict(value)

Returns true if the value is an positive or negative Decimal value

Example :

 isSignedDecimalStrict('123') == true
 isSignedDecimalStrict('+123.23') == true
 isSignedDecimalStrict('-123.23 ') == false
 isSignedDecimalStrict('+123.34 ') == false
 
 

isSignedDecimal(value)

Returns the same as isSignedDecimalStrict() except white-space is trimmed first

Example :

 isSignedDecimal('123') == true
 isSignedDecimal('+123.23') == true
 isSignedDecimal('-123.23 ') == true
 isSignedDecimal('+123.34 ') == true
 isSignedDecimal('123.34+ ') == false
 
 

isCurrencyStrict(value)

Returns true if the value is an positive Currency value. This can include an optional $ at the start

Example :

 isCurrencyStrict('123') == true
 isCurrencyStrict('123.34 ') == true
 isCurrencyStrict('$123.23') == true
 isCurrencyStrict('$123.34 ') == false
 isCurrencyStrict('-$123.23') == false
 
 

isCurrency(value)

Returns the same as isCurrencyStrict() except white-space is trimmed first

Example :

 isCurrency('123') == true
 isCurrency('123.34 ') == true
 isCurrency('$123.23') == true
 isCurrency('$123.34 ') == true
 isCurrency('-$123.23') == false
 
 

isSignedCurrencyStrict(value)

Returns true if the value is an positive or negative Currency value. This can include an optional $ at the start and brackets to indicate negative as in (1234.00) or ($1234.00)

Example :

 isSignedCurrencyStrict('123') == true
 isSignedCurrencyStrict('123.34 ') == true
 isSignedCurrencyStrict('$123.23') == true
 isSignedCurrencyStrict('($123.23)') == true
 isSignedCurrencyStrict('(123.23)') == true
 isSignedCurrencyStrict('$123.34 ') == false
 isSignedCurrencyStrict('-$123.23') == false
 isSignedCurrencyStrict('($123.23') == false
 
 

isSignedCurrency(value)

Returns the same as isSignedCurrencyStrict() except white-space is trimmed first

Example :

 isSignedCurrency('123') == true
 isSignedCurrency('123.34 ') == true
 isSignedCurrency('$123.23') == true
 isSignedCurrency(' ($123.23) ') == true
 isSignedCurrency('(123.23)') == true
 isSignedCurrency('$123.34 ') == true
 isSignedCurrency('-$123.23') == false
 isSignedCurrency('($123.23') == false
 
 

insideRange(value, min, max)

Returns true if the value is >= min and <= max

Example :

 // assume value is '40'
 insideRange(parseInt(value), 20, 100) == true 
 // assume value is '10'
 insideRange(parseInt(value), 20, 100) == true
 // assume value is '40'
 insideRange(value, 20, 100) == false
                // because value is a string
 
 

outsideRange(value, min, max)

Returns true if the value is < min or gt; max

Example :

 // assume value is '40'
 outsideRange(parseInt(value), 20, 100) == false
 // assume value is '10'
 outsideRange(parseInt(value), 20, 100) == true
 // assume value is '10'
 outsideRange(value, 20, 100) == false
                // because value is a string
 
 

Date Functions

The following date related functions use the same 'format' strings as the java.text.SimpleDateFormat class, with minor exceptions. The format string consists of the following abbreviations:

 Field        | Full Form          | Short Form
 -------------+--------------------+-----------------------
 Year         | yyyy (4 digits)    | yy (2 digits), y (2 or 4 digits)
 Month        | MMM (name or abbr.)| MM (2 digits), M (1 or 2 digits)
              | NNN (abbr.)        |
 Day of Month | dd (2 digits)      | d (1 or 2 digits)
 Day of Week  | EE (name)          | E (abbr)
 Hour (1-12)  | hh (2 digits)      | h (1 or 2 digits)
 Hour (0-23)  | HH (2 digits)      | H (1 or 2 digits)
 Hour (0-11)  | KK (2 digits)      | K (1 or 2 digits)
 Hour (1-24)  | kk (2 digits)      | k (1 or 2 digits)
 Minute       | mm (2 digits)      | m (1 or 2 digits)
 Second       | ss (2 digits)      | s (1 or 2 digits)
 AM/PM        | a                  |
 

NOTE THE DIFFERENCE BETWEEN MM and mm! Month=MM, not mm!

 "MMM d, y" matches: January 01, 2000
                     Dec 1, 1900
                     Nov 20, 00
 
 "M/d/yy"   matches: 01/20/00
                     9/2/00
 
 "MMM dd, yyyy hh:mm:ssa" matches: 
                                                "January 01, 2000 12:30:45AM"
 

isDateStrict(value, format)

Returns true if the value is a date object according to the provided date format.

Example :

 // assume value is 'Jan 15, 1980'
    isDate(value,'MMM d, y') == true
 // assume value is '  Jan 15, 1980  '
    isDate(value,'MMM d, y') == false
 // assume value is 'Jan 15, 1980'
    isDate(value,'M/d/yy') == false
 // assume value is '01/15/1980'
    isDate(value,'M/d/yy') == true
 // assume value is '  01  / 15 / 1980 '
    isDate(value,'M/d/yy') == false
 
 

isDate(value)

Returns the same as isDateStrict() except white-space is trimmed first

Example :

 // assume value is 'Jan 15, 1980'
    isDate(value,'MMM d, y') == true
 // assume value is '  Jan 15, 1980  '
    isDate(value,'MMM d, y') == true
 // assume value is 'Jan 15, 1980'
    isDate(value,'M/d/yy') == false
 // assume value is '01/15/1980'
    isDate(value,'M/d/yy') == true
 // assume value is '  01  / 15 / 1980 '
    isDate(value,'M/d/yy') == true
 
 

dateIsValidStrict(value, preferEuroFormats)

This function takes a date string and tries to match it to a number of possible date formats to get the value. It will try to match against the following international formats, in this order:

 y-M-d   MMM d, y   MMM d,y   y-MMM-d   d-MMM-y  MMM d
 M/d/y   M-d-y      M.d.y     MMM-d     M/d      M-d
 d/M/y   d-M-y      d.M.y     d-MMM     d/M      d-M
 

The preferEuroFormats argument may be passed to instruct the method to search for formats like d/M/y (European format) before M/d/y (American).

Example :

 // assume value is 'Jan 15, 1980'
    dateIsValidStrict(value) == true
 // assume value is '  Jan 15, 1980  '
    dateIsValidStrict(value) == false
 // assume value is 'Jan 15, 1980'
    dateIsValidStrict(value) == true
 // assume value is '01/15/1980'
    dateIsValidStrict(value) == true
 // assume value is '  01  / 15 / 1980 '
    dateIsValidStrict(value) == false
 
 

dateIsValid(value, preferEuroFormats)

This function is the same as dateIsValidStrict() however whitespace is trimmed first.

Example :

 // assume value is 'Jan 15, 1980'
    dateIsValid(value) == true
 // assume value is '  Jan 15, 1980  '
    dateIsValid(value) == true
 // assume value is 'Jan 15, 1980'
    dateIsValid(value) == true
 // assume value is '01/15/1980'
    dateIsValid(value) == true
 // assume value is '  01  / 15 / 1980 '
    dateIsValid(value) == true
 
 

dateIsAfter(dateValue1, dateformat1, dateValue2, dateformat2)

This function will compare two date strings, using the specified date formats, to see if the first is after the second date.

Returns true if dateValue1 is after dateValue2 or false if its not or the date strings and formats are invalid.

Example :

    dateIsAfter('01/15/1980','MM/dd/yyyy', '08/01/1980', 'dd/MM/yyyy') == true
 
 

dateGetValue(value, [preferEuroFormats] [,format])

This function will a JavaScript Date object from the given value. If the format parameter is specified, then it will be used to intepret thet date otherwise the dateIsValid parse routine is used.

You really should precede this call with a date validation routine to ensure the date can be parsed.

Example :

    dt = dateGetValue('01/15/1980')
 
 

fieldIsValid(fieldName)

Returns true if the field, identified by fieldName, is valid according to its associated validation rules.

The fieldName must be one defined by ValidationRuleSet.getName()

Example :

 fieldIsValid('postcode')       
                // ok assuming postcode exists
 fieldIsValid('postcodeXX')     
                // will ASSERT if postcodeXX does not exist
 fieldIsValid(value)                    
                // very unlikely to do what you want
 
 

fieldIsEmpty(fieldName)

Returns true if the field, identified by fieldName, has no value, has a lenght of zero or is all whitespace.

The fieldName must be one defined by ValidationRuleSet.getName()

Example :

 fieldIsEmpty('postcode')       
                // true of postcode == null || trim(postcode).length == 0
 fieldIsEmpty('postcodeXX')     
                // will ASSERT if postcodeXX does not exist
 fieldIsEmpty(value)                    
                // very unlikely to do what you want
 
 

fieldIsNull(fieldName)

Returns true if the field, identified by fieldName, has a null value or has a length of zero.

The fieldName must be one defined by ValidationRuleSet.getName()

Example :

 fieldIsNull('postcode')                
                // true of postcode == null
 fieldIsNull('postcode')                
                // false of trim(postcode).length == 0 
                // (becauses its not null)
 fieldIsNull('postcodeXX')      
                // will ASSERT if postcodeXX does not exist
 fieldIsNull(value)                     
                // very unlikely to do what you want
 
 

fieldHasValue(fieldName)

Returns true if the field, identified by fieldName, has a non null value that is not white-space.

The fieldName must be one defined by ValidationRuleSet.getName()

Example :

 fieldHasValue('postcode')      
                // true of postcode != null && trim(postcode).length > 0
 fieldHasValue('postcodeXX')    
                // will ASSERT if postcodeXX does not exist
 fieldHasValue(value)           
                // very unlikely to do what you want
 
 

fieldGetValue(fieldName)

Returns the current value of a field, identified by fieldName. This function in and of itself does not necessarily equate to true and should be used in conjunction with other expresions.

The fieldName must be one defined by ValidationRuleSet.getName()

Example :

 fieldGetValue('postcode')      
                // return the value of the postcode field
 fieldGetValue('postcodeXX')    
                // will ASSERT if postcodeXX does not exist
 fieldGetValue(value)           
                // very unlikely to do what you want
 
 

trim(value)

Trims the whitespace from the start and end of a javascript expression.

Example :

 trim('  abcd  ')       
                // returns 'abcd'
 
 

You can define custom validation functions outside the rule itself. For example this is valid javascript rule for an interger value that is even.

 'function isEven(value) { return parseInt(value) % 2 == 0;} isInteger(value) && isEven(value)'
 

Parameters:

validateable - - the Validateable to be validated.

runOption - - when to run the rule. Can be either RUN_OB_BLUR or RUN_ON_SUBMIT.

Returns:

returns a JavaScript expression that can be used to validate the rule on the client or null if no rule to to be run.

isValid

boolean isValid(Validateable validateable)

This returns true if the Validateable is in fact valid. This is used when the rule is run on the server.

Parameters:

validateable - - the Validateable to be validated.

Returns:

true if the Validateable is in fact valid.