JTec Validator - 5 minutes introduction

Validation

You have seen, that xml validation descriptor describes several "Validations". Validation ( de.jtec.validator.Validation ) is itself pretty dumb and acts as container for condition tree (which does all the work). Validation also stores reference to property name (descriptive - what property we are validating), message (which could be also key for message bundle, i18n is out of scope here) and which condition evalation result indicates failure (default is false).

Once validation object is set up, you can pass whatever object you like to valdate() method. As result you will get ValidationFailure ( holding configured property name and message or just null if condition was satisfied.

Conditions are workhorses of JTec Validation. They roughly split into 2 main groups:

Composite conditions: Provide logical grouping of other conidtions. Do not access object instance under validation. They can be seen as nonleaf nodes in rule tree
Primitive conditions: Access object and perform some validations. They are leaf nodes in validation tree.

Composite Conditions

Composite conditions act as containers for other conditions, and delegate validation to them. Outcome of such condition depends on its children. At the moment there are tre types of them:

or: Only one of child condition shall succeed ( evaluate to true ) for this condition to success.
and: All child conditions have to succedd for success of parent.
not: Outcome of this condition is reverse of outcome of single child. (technically there could be more, but only first will be evaluated)

Of course composite conditions behave politely and cancel evaluation of subconditions as soon as the outcome is known. This if first condition (and) succeeds, second will be not evaluated. Those 3 conditions define functionally complete decision trees. Of cours it would be posible with just one condition, but this would be not readable.

<or>
    <and>
        <match property="country" pattern="germany"/>
        <match property="zip" pattern="[0-9]{5}"/>
    </and>
    <and>
        <match property="country" pattern="GB"/>
        <match property="zip" pattern="[a-zA-Z]{1}[0-9]{2}\s[a-zA-Z]{1}[0-9]{2}"/>
    </and>
</or>

Primitive conditions

Primitive conditions can not have child conditions, but instead they do real validation work on supplied objects. Most primitive conditions operate on some property of supplied object. Property is extracted by means of commons-beanutils, so you may use whatever notation is acceptable by this library.

Boolean conditions

There are 2 boolean conditions, always evaluating to "true" or "false" (and as you may imagine, they are referenced in xml as <true> and <false>) Puprose of boolean condition is to provide some fallback decisions for composite conditions.

<or>
    <match property="country" pattern="germany"/>
    <match property="country" pattern="usa"/>
    <match property="country" pattern="france"/>
    <false/>
</or>

This would force failure if none of previous conditions evaluates as true (i.e country is not in the list)

Pattern matching

Pattern mathcing is important feature in evaluation. Pattern mathcing conditions include:

null
notnull
match

While null and notnull simply assert value of certain property, match applies regular expression to stringified value. It uses java.util.regex.Pattern to do its job.

<match property="country" pattern="germany"/>
<match property="zip" pattern="[0-9]{5}"/>

Class assertion

Sometimes it is important to know what object we have to validate. class condition asserts that object is of certain type

<or>
    <and>
        <class className="Foo"/>
        <match property="bar" patttern="glum"/>
    </and>
    <and>
        <class className="Bar"/>
        <match property="blurge" patttern="bang"/>
    </and>
</or>

Numeric conditions

Of course, we need to validate numeric values. Following numerical conditions are available:

more (de.jtec.validator.condition.More)
moreOrEquals (e.jtec.validator.condition.MoreOrEquals)
less (de.jtec.validator.condition.Less)
lessOrEquals (de.jtec.validator.condition.LessOrEquals)
equalTo (de.jtec.validator.condition.Equals)
between (de.jtec.validator.condition.Between)
betweenleft (de.jtec.validator.condition.BetweenL)

Consult javadocs for available properties.

Build conditions

At the moment there are 2 ways to create condition trees - you do this programatically with java code (all conditions have sane and developer friendly constructors and configuration methids) - see unit test fo examples how it is done. Alternatively, there is XML configuration available

StringReader config = new StringReader(
    "<validator>" +
    "<validation property=\"foo\" glem=\"glam\" message=\"bar\" fail=\"false\"/>" +
    "<validation property=\"baz\" message=\"bang\" fail=\"true\"/>" +
    "</validator>"
    );

XmlValidator validator = new XmlValidator(config);

Now your validator is ready to validate whatever you feed him.

Project Documentation