Creating your own rules

saoj — GMT

A rule validates whether an action input value is valid or not to be passed along to the action. To learn about rules let's code a simple [i]NegativeRule [/i]class that validates only negative numbers.
[code]
import java.util.HashMap;
import java.util.Map;

public class NegativeRule extends BasicRule {

public NegativeRule() { }

public boolean check(String value) {

try {

int x = Integer.parseInt(value);

return x < 0;

} catch(Exception e) {

return false;
}
}

public Map getTokens() {
return null; // no tokens...
}

}
[/code]
When you extend [i]BasicRule [/i]you should implement two methods: check() and getTokens().

:arrow: check(String value): In this method you receive the value you are suppose to validate and just do it, however you want to, returning true or false.

:arrow: getTokens(): In this method you return a map with tokens and their values to be used by error messages. The default implementation in BasicRule is to return null, so you should only implement this method if you have tokens to return.

A token is used inside error messages so that it can be substituted for values associated with the rule. For example, in our simple rule above, the negative number has no minimum boundary. Let's change it to include a possible minimum:
[code]
import java.util.HashMap;
import java.util.Map;

public class NegativeRule extends BasicRule {

private final int min;
private final Map tokens = new HashMap();

public NegativeRule() {
this.min = Integer.MIN_VALUE;
this.tokens.put("min", String.valueOf(min));
}

public NegativeRule(int min) {
this.min = min;
this.tokens.put("min", String.valueOf(min));
}

public boolean check(String value) {

try {

int x = Integer.parseInt(value);

return x < 0 && x >= min;

} catch(Exception e) {

return false;
}
}

public Map getTokens() {
return tokens;
}
}
[/code]
Note that now we have the possibility to validate the input value based on a minimum number and we are returning the token "min" with whatever value is given to that minimum number. Therefore you may have an error message like the one below:
[code]
invalid_number = Your negative number should be bigger than %min%.
[/code]
The %min% token is substituted with the value returned in the [i]getTokens() [/i]method. The [i]IntegerRule [/i]that comes with Mentawai also returns tokens for its min and max values. The tokens of a rule are nothing more than its properties that you may want to display along with the error messages.

There are other types of validation that are not solely based in the value itself. For example you may want to perform validation based on the user locale and you may want to perform validation of one field based on another field.

The most common example of a validation that depends on the locale is date validation. Depending on the user locale the date 12/30/2008 may be valid or not. Below is the source code of a simple rule to validate dates. Note that we are now extending [i]LocaleRule [/i]instead of [i]BasicRule[/i].
[code]
import java.util.*;
import java.text.*;

public class DateRule extends LocaleRule {

private static final int STYLE = DateFormat.SHORT;

public DateRule() {

}

public boolean check(String value, Locale locale) {

DateFormat df = DateFormat.getDateInstance(style, locale);

df.setLenient(false);

try {

df.parse(value);

return true;

} catch(ParseException e) {

return false;

}
}

public Map getTokens() {

return null;
}

}
[/code]
Note that now the [i]check()[/i] method receives not just the value but also the locale of the user performing the request. You should use the locale in any way you want to perform the validation. Mentawai already comes with a complete [i]DateRule [/i]so you should not need to code a rule for dates. This was just an example for you to understand how the [i]LocaleRule [/i]works in case you want to write your own.

The last form of common validation is when you need to compare two fields to determine whether one field is valid or not. If you thought about password and password confirmation you were right. For that we can extend the [i]CrossRule [/i]class. Check the source below for a simple [i]EqualRule [/i]that validates whether two fields have the same value:
[code]
import java.util.HashMap;
import java.util.Map;

public class EqualRule extends CrossRule {

private final String[] fields;

public EqualRule(String field1, String field2) {
this.fields = new String[] { field1, field2 };
}

protected String[] getFieldsToValidate() {
return fields;
}

public boolean check(String[] values) {

return values[0].equals(values[1]);
}

public Map getTokens() {
return null;
}
}
[/code]
When inheriting from [i]CrossRule [/i]you should implement two abstract methods:

:arrow: getFieldsToValidate() should return an array of the field names that will be compared.

:arrow: check(String[] values) receives the values of the fields indicated by the[i] getFieldsToValidate()[/i] method, so that you can perform any comparison you want to validate them.

Note that Mentawai gets the field values for you from the action input and pass them along with the check method so that you can compare them and return the validation result. Mentawai already comes with a complete [i]EqualRule [/i] in the [i]org.mentawai.rule[/i] package.

Another very useful built-in rule that you can use for your advantage is the [i]RegexRule[/i]. Check below how a [i]SocialSecurityNumberRule [/i]could be implemented by inheriting from [i]RegexRule[/i]:
[code]
public class SSNRule extends RegexRule {

/** The regex to use for SSN validation. */
public static final String PATTERN = "^\\d\\d\\d\\-\\d\\d\\-\\d\\d\\d\\d$";

public SSNRule() {
super(PATTERN);
}
}
[/code]
You could have also used the [i]RegexRule [/i]with the Social Security Number pattern without the need to create a new rule for it. See below:
[code]
Rule rule = new RegexRule("^\\d\\d\\d\\-\\d\\d\\-\\d\\d\\d\\d$");
[/code]
As you can see, by inheriting from [i]BasicRule[/i], [i]LocaleRule[/i], [i]CrossRule [/i]and [i]RegexRule [/i]you can perform any kind of validation for your action input values.

Latest posts for the topic "Creating your own rules"

Creating your own rules