|
The Java Object Validation Framework |
|
| i-screen.org | ||
|
Download (SourceForge Hosted) Documentation
Articles Feedback |
Validator CatalogiScreen comes with several pre-built Validators. They are available from the org.iscreen.validators.xml file. They can be included via the following configuration:
<include file="org/iscreen/validators.xml" />
StringValidatorThe StringValidator validates the lengths of String objects. The following configuration defines the Validator in the org.iscreen.validators.xml file:
<validator id="StringValidator"
class="org.iscreen.validators.StringValidator">
<failure property="minLengthFailure" key="vf.minLength" />
<failure property="maxLengthFailure" key="vf.maxLength" />
<failure property="nullFailure" key="vf.null" />
</validator>
The failure messages are defined as this (in the org.iscreen.messages.properties):
vf.minLength=${label} must be at least ${validator.minLength} characters long.
vf.maxLength=${label} must not be greater than ${validator.maxLength} characters long.
vf.null=${label} is a required field.
The StringValidator also supports two constraints: minLength : the minimum number of characters the String must have. If this is not specified, then the String can be null (and no cause a null failure). If it is non-null (zero or greater) and the String is null, then a null failure is reported (as opposed to a minLengthFailure). maxLength : the maximum number of characters the String can have. If this is not specified, then the maximum length is not checked (meaning, it can be as long as it wants). The StringValidator uses the org.iscreen.SimpleBean as the mapping bean, and has a single property named 'value'. The following is an example of referencing the StringValidator within your configuration. It will ensure that the String being validated is at least one character long, but no greater than ten.
<include file="org/iscreen/validators.xml" />
<validation-set id="someSet">
<use-validator ref="org.iscreen.StringValidator">
<label>Some label</label>
<mapping from="someProperty" to="value" />
<!-- mapping can also leave off the 'to' attribute, as the default value for it is 'value' -->
<constraint property="minLength">1</constraint>
<constraint property="maxLength">10</constraint>
</use-validator>
</validation-set>
In addition, the StringValidator returns the length of the string when a failure occurs (but only if it's a min or max length failure). DateFormatValidatorThe DateFormatValidator validates the date format of String objects. The following configuration defines the Validator in the org.iscreen.validators.xml file:
<validator id="DateFormatValidator"
class="org.iscreen.validators.DateFormatValidator">
<failure property="defaultFailure" key="vf.dateFormat" />
</validator>
The failure messages are defined as this (in the org.iscreen.messages.properties):
vf.dateFormat=The date format for ${label} is ${validator.displayFormat}.
The DateFormatValidator also supports three constraints: format : the date format to use (must be a valid java.text.SimpleDateFormat pattern). The default value (if not specified) for this constraint is MM/dd/yyyy. displayFormat : the date format to display to the user via the failure message. The default value (if not specified) for this constraint is MM/DD/YYYY. lenient : defines whether the validation should be lenient or not (see the setLenient() method on the java.text.SimpleDateFormat class). If not specified, this constraint is set to false. The DateFormatValidator uses the org.iscreen.SimpleBean as the mapping bean, and has a single property named 'value'. The following is an example of referencing the DateFormatValidator within your configuration. It will ensure that the String being validated is formatted using the SimpleDateFormat's pattern of MMMM dd, yyyy (e.g. July 1, 2000). The format will be lenient, and if there's a failure, the date format displayed to the user will be month day, year.
<include file="org/iscreen/validators.xml" />
<validation-set id="someSet">
<use-validator ref="org.iscreen.DateFormatValidator">
<label>Some label</label>
<mapping from="someProperty" to="value" />
<!-- mapping call also leave off the to attribute, as the default value for it is 'value' -->
<constraint property="format">MMMM dd, yyyy</constraint>
<constraint property="displayFormat">month day, year</constraint>
<constraint proeprty="lenient">true</constraint>
</use-validator>
</validation-set>
In addition, the DateFormatValidator returns the invalid date string when the format is invalid (via the failure property on the OGNL root). DateRangeValidatorThe DateRangeValidator validates a date range or a date within a range. First, if a range (a 'from' and 'to' dates) is fully defined (neither are null), then the dates are validated to ensure that the 'to' date is equal to or after the 'from' date. Second, if a 'date' is defined (non-null), it is validated against the date range (so, the 'date' must be equal to or after the 'from' date if it is non-null, and it must be before or equal to the 'to' date if it is non-null). The following configuration defines the Validator in the org.iscreen.validators.xml file (note that there are two failures for whether the 'date' is before the 'from' date or after the 'to' date):
<validator id="DateRangeValidator"
class="org.iscreen.validators.DateRangeValidator">
<failure property="rangeFailure" key="vf.dateRange" />
<failure property="beforeFailure" key="vf.dateBeforeRange" />
<failure property="afterFailure" key="vf.dateAfterRange" />
</validator>
The failure messages are defined as this (in the org.iscreen.messages.properties):
vf.dateRange=The beginning date for ${label} must be equal to or before the ending date.
vf.dateBeforeRange=The date for ${label} cannot come before ${new java.text.SimpleDateFormat( "MMMM dd, yyyy" ).format( failure )}.
vf.dateAfterRange=The date for ${label} cannot come after ${new java.text.SimpleDateFormat( "MMMM dd, yyyy" ).format( failure )}.
Note that the 'beforeFailure' is reported with the 'from' date being the failure object. For the 'afterFailure' failure, the 'to' date is reported as the failure object. No failure object is reported for the 'rangeFailure' failure. The DateRangeValidator does not have any constraints. The DateRangeValidator uses an internal mapping bean, with three properties: 'to', 'from', and 'date'. The following is an example of referencing the DateRangeValidator within your configuration. It will ensure that the 'fromDateProperty' date (must be a java.util.Date) is before (or equal to) the 'toDateProperty' date (must be a java.util.Date). It will also verify that the 'someDate' date (must be a java.util.Date) is within the 'from' and 'to' date range. Note that none of the dates have to be non-null. For example, if one of the 'from' or 'to' dates are null, then the range check is ignored, but the check for the 'date' property against the non-null one is still done. If the 'date' property is null, then it is not checked against the range. If none of them are non-null (or just one of the 'from' or 'to' dates), then nothing is checked.
<include file="org/iscreen/validators.xml" />
<validation-set id="someSet">
<use-validator ref="org.iscreen.DateRangeValidator">
<label>Some label</label>
<mapping from="fromDateProperty" to="from" />
<mapping from="toDateProperty" to="to" />
<mapping from="someDate" to="date" />
</use-validator>
</validation-set>
NullValidatorThe NullValidator validates the existence of a value (it can't be null). The following configuration defines the Validator in the org.iscreen.validators.xml file:
<validator id="NullValidator"
class="org.iscreen.validators.NullValidator">
<failure property="defaultFailure" key="vf.null" />
</validator>
The failure message is defined as this (in the org.iscreen.messages.properties):
vf.null=${label} is a required field.
The NullValidator has no constraints. The NullValidator uses the org.iscreen.SimpleBean as the mapping bean, and has a single property named 'value'. The following is an example of referencing the NullValidator within your configuration. It will ensure that the object being validated is not null.
<include file="org/iscreen/validators.xml" />
<validation-set id="someSet">
<use-validator ref="org.iscreen.NullValidator">
<label>Some label</label>
<mapping from="someProperty" to="value" />
<!-- mapping can also leave off the 'to' attribute, as the default value for it is 'value' -->
</use-validator>
</validation-set>
RegexValidatorThe RegexValidator uses a regular expression to validate the String being validated. The following configuration defines the Validator in the org.iscreen.validators.xml file:
<validator id="RegexValidator"
class="org.iscreen.validators.RegularExpressionValidator">
<failure property="defaultFailure" key="vf.regex" />
</validator>
The failure message is defined as this (in the org.iscreen.messages.properties):
vf.regex=The value of ${label} does not match the defined regular expression.
The RegexValidator has two constraints: regex : This is the regular expression that's used to validate the incoming String. There is no default value, so this is a required constraint. If a failure is reported, the String being validated is reported as the failure object. allowNull : This constraint defaults to false, and specifies whether a failure will be reported if the String is null. If it's null, and this constraint is set to false, then the String being validated is ignored. The RegexValidator uses the org.iscreen.SimpleBean as the mapping bean, and has a single property named 'value'. The following is an example of referencing the RegexValidator within your configuration. It will ensure that the String being validated matches the regular expression.
<include file="org/iscreen/validators.xml" />
<validation-set id="someSet">
<use-validator ref="org.iscreen.RegexValidator">
<label>Some label</label>
<mapping from="someProperty" to="value" />
<!-- mapping can also leave off the 'to' attribute, as the default value for it is 'value' -->
<constraint property="regex">some regular expression</constraint>
<constraint property="allowNull">true</constraint>
</use-validator>
</validation-set>
EmailAddressValidatorThe EmailAddressValidator validates a String to ensure that it follows the proper format for email addresses. It does NOT validate whether the email address actually exists, or whether the domain name is valid or anything like that. It uses the regular expression validator by defining a regex that tests for the proper email address format. It has the same constraints, etc. that the RegexValidator has. The following configuration defines the Validator in the org.iscreen.validators.xml file:
<validator id="EmailAddressValidator" ref="RegexValidator">
<constraint property="regex">^[_A-Za-z0-9-]+(\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*$</constraint>
<failure property="defaultFailure" key="vf.emailAddress" />
</validator>
The failure message is defined as this (in the org.iscreen.messages.properties):
vf.emailAddress=The address ${failure} given for ${label} is not in a valid email address format.
The following is an example of referencing the EmailAddressValidator within your configuration. It will ensure that the String being validated conforms to proper email address format.
<include file="org/iscreen/validators.xml" />
<validation-set id="someSet">
<use-validator ref="org.iscreen.EmailAddressValidator">
<label>Some label</label>
<mapping from="someProperty" to="value" />
<!-- mapping can also leave off the 'to' attribute, as the default value for it is 'value' -->
</use-validator>
</validation-set>
NumberRangeValidatorThe NumberRangeValidator validates the range of java.lang.Number objects objects (though it can accept String objects that are parsable into numbers). The following configuration defines the Validator in the org.iscreen.validators.xml file:
<validator id="NumberRangeValidator"
class="org.iscreen.validators.NumberRangeValidator">
<failure property="rangeFailure" key="vf.NumberOutOfRange" />
<failure property="invalidNumberFailure" key="vf.InvalidNumber" />
</validator>
The failure messages are defined as this (in the org.iscreen.messages.properties):
vf.numberOutOfRange=${label} must be at least ${validator.minimumValue} and no greater than ${validator.maximumValue}.
vf.invalidNumber=${label} must be a number.
The NumberRangeValidator also supports two constraints: minimumValue : the minimum number the value can be. It's default is zero. maximumValue : the maximum number the value can be. It's default is Integer.MAX_VALUE, but if it's set to -1, then the value can be infinite (effectively, Integer.MAX_VALUE). The NumberRangeValidator uses the org.iscreen.SimpleBean as the mapping bean, and has a single property named 'value'. The value must be a java.lang.Number. The following is an example of referencing the NumberRangeValidator within your configuration. It will ensure that the number is at least 1, but no greater than 100.
<include file="org/iscreen/validators.xml" />
<validation-set id="someSet">
<use-validator ref="org.iscreen.NumberRangeValidator">
<label>Some label</label>
<mapping from="someProperty" to="value" />
<!-- mapping can also leave off the 'to' attribute, as the default value for it is 'value' -->
<constraint property="minimumValue">1</constraint>
<constraint property="maximumValue">100</constraint>
</use-validator>
</validation-set>
In addition, the NumberRangeValidator returns the value of the number when a failure occurs (but only for a range failure). ExpressionValidatorThe ExpressionValidator validates objects using either OGNL or MVEL expressions. The following configuration defines the Validator in the org.iscreen.validators.xml file:
<validator id="ExpressionValidator"
class="org.iscreen.ognl.validators.ExpressionValidator">
<failure property="defaultFailure" key="vf.ognlExp" />
</validator>
The failure messages are defined as this (in the org.iscreen.messages.properties):
vf.ognlExp=${label} is invalid.
The ExpressionValidator only supports one constraint: expression : this is the OGNL or MVEL expression that MUST evaluate to a boolean expression. If the expression evaluates to false, then a failure occurs. The bean being validated is the "root" object in the expression. The ExpressionValidator uses the org.iscreen.SimpleBean as the mapping bean, and has a single property named 'value'. The following is an example of referencing the ExpressionValidator within your configuration. It checks the 'someFlag' property on the bean being validated to ensure that it's true.
<include file="org/iscreen/validators.xml" />
<validation-set id="someSet">
<use-validator ref="org.iscreen.ExpressionValidator">
<label>Some label</label>
<constraint property="expression">someFlag == true</constraint>
</use-validator>
</validation-set>
In addition, the ExpressionValidator returns the bean being validated when a failure occurs. |
|
|
|