An Overview of the Standard Rules | Professional Jakarta Struts (Programmer to Programmer)

< Day Day Up >

Before you start writing your own rules, you should become familiar with Table 12.1, which describes the standard rules included with the framework. As you can see, you get a lot of functionality with very little work.

Table 12.1: Standard Rules
Rule Name	Description
Required	The field is required. It must be present for the form to be valid and takes no variables.
Mask	The field must match the specified regular expression (Perl 5 style). The Mask rule has a variable called mask. The mask variable is the regular expression.
maxlength	The field must have fewer characters than the specified maximum length. The maxlength rule has a variable called maxlength. The maxlength variable specifies the maximum number of characters allowed.
minlength	The field must have more characters than the specified minimum length. The minlength rule has a variable called minlength. The minlength variable specifies the minimum number of characters allowed.
intrange, floatrange	The field must equal a numeric value between the min and max variables.
byte, short, integer, long, float, double	The field must parse to one of these standard Java types (rules names equate to the expected Java type).
Date	The field must parse to a date. The optional variable datePattern specifies the date pattern (see java.text.SimpleDateFormat in the JavaDocs to learn how to create the date patterns). You can also pass a strict variable equal to false to allow a lenient interpretation of dates, i.e., 05/05/99 = 5/5/99. If you do not specify a date pattern, the short date form for the current locale is used, i.e., (DateFormat.SHORT).
creditCard	The field must be a possible credit card number.
Email	The field must be a possible e-mail address.

Let's cover using several combinations of the rules in Table 13.1 and see the ramifications of doing so. We don't cover all of the rules—just the most useful ones. Once you learn how to use the complex rules, using the simple ones is a straightforward process.

Using Two Rules on the Same Field (the maxfield Rule)

In the first example, we used one rule against one field in one form. You can apply many rules to the same field. In fact, it is common to apply more than one rule to the same field. Let's extend our validation rules for the username. Suppose you want to add the ability to limit the maximum characters in a username to 11. You would follow these steps:

Specify that the userName field correspond to the maxlength rule.
Add the error message for the maxlength rule to the resource bundle.
Configure the value of the maxlength variable to 11.
Specify that the value of the rules' maxlength variable be the second argument to the error message.

Note that you have to go through fewer steps because you are adding this new rule to the existing field. As we explained, the hardest part of the Validator Framework is getting started. Once you are using it, adding new rules to fields is easy.

Step 1 is to specify that the userName field correspond to the maxlength rule. You already set up that field, so now all you have to do is add maxlength to the depends attribute of the userName field as follows:

           <field property="userName"                       depends="minlength,maxlength">

This code states that the userName field will not be valid unless both the minlength and the maxlength validation rules pass.

In step 2, you add the error message for the maxlength rule to the resource bundle. This is a simple matter of opening the application.properties file and adding this entry:

 errors.maxlength={0} can not be greater than {1} characters.

Of course, you are free to change the wording of the message.

Remember that samples of the error messages for each rule can be found in the comments of the validation-rules.xml file. You may want to copy and paste all of the messages at once.

Remember that the {0} will be replaced with the first argument and that the {1} will be replaced with the second argument as with java.text.MessageFormat.

Configuring the value of the maxlength variable to 11 is the third step. To use the maxlength rule, you need to pass it the maxlength variable as follows:

           <form name="inputForm">                <field property="userName"                       depends="minlength,maxlength">                ...                     <var>                          <var-name>maxlength</var-name>                          <var-value>11</var-value>                     </var>

The final step is to specify that the value of the rules' maxlength variable be the second argument to the error message. You do not have to specify the first argument to the field because you did this when you configured the minlength rule. However, you do have to specify an additional second argument (arg1). The second argument is activated only if the maxlength validation rule is not valid:

       <form name="inputForm">            <field property="userName"                   depends="minlength,maxlength">                 <arg0 key="inputForm.userName"/>                 <arg1 key="${var:minlength}"                       name="minlength" resource="false"/>                 <arg1 key="${var:maxlength}"                       name="maxlength" resource="false"/>                 ...

The new second argument (argl) states that the maxlength variable will be passed as the second argument to the error message (errors.maxlength from the resource bundle).

That's it. Now the userName field is using both the minlength and the maxlength rule. Listing 12.3 shows the complete form for using both minlength and maxlength.

Listing 12.3: Form that uses minlength and maxlength.

       <form name="inputForm">            <field property="userName"                   depends="minlength,maxlength">                 <arg0 key="inputForm.userName"/>                 <argl key="${var:minlength}"                       name="minlength" resource="false"/>                 <argl key=^"${var:maxlength}"                       name="maxlength" resource="false"/>                 <var>                      <var-name>minlength</var-name>                      <var-value>5</var-value>                 </var>                 <var>                      <var-name>maxlength</var-name>                      <var-value>11</var-value>                 </var>            </field>       </form>

Using the Mask Rule

The mask rule is fairly flexible and eliminates the need for writing a lot of custom validation rules. Because the mask rule uses Perl 5-style regular expressions, it is very powerful—assuming, of course, that you know regular expressions well. If you don't, now is a good time to learn. If you have used regular expressions with Perl, Python, or JavaScript, then you are in good shape. Also, if you have used the regular expression package that ships with JDK 1.4 and greater, you will do fine because most of the syntax works the same.

With the mask rule, you are essentially writing your own rule. When you use the mask rule, you are implementing the rule in regular expression syntax instead of Java. Since you are writing your own rule, starting with a blank slate if you will, the default message often does not make sense. Also, having a simple default message—like those with minlength, maxlength, and date—will probably not be useful. Thus, you need to specify your own custom message that the mask rule will use. The message should explain what the regular expression validation routine does so that the end user can understand how to fix the problem.

To demonstrate the mask rule, let's say that our username has to begin with a letter and that it can contain letters, numbers, and underscores.

The steps for using the mask rule and defining your own custom message are:

Specify that the userName field correspond to the mask rule.
Specify an error message key for the mask rule.
Add the error message for the mask rule to the resource bundle.
Configure the value of the mask variable to a pattern that implements your business rules.

              <form name="inputForm">                   <field property="userName"                          depends="minlength,maxlength,mask">                        <msg name="mask"                             key="inputForm.userName.mask"/>                        <arg0 key="inputForm.userName"/>                        <arg1 key="${var:minlength}"                              name="minlength" resource="false"/>                        <arg1 key="${var:maxlength}"                              name="maxlength" resource="false"/>                        <var>                             <var-name>minlength</var-name>                             <var-value>5</var-value>                        </var>                        <var>                             <var-name>maxlength</var-name>                             <var-value>11</var-value>                        </var>                        <var>                             <var-name>mask</var-name>                             <var-value>^[a–zA–Z]{1}[a–zA–Z0–    9_]*$</var-value>                        </var>                   </field>              </form>

We will now examine these four steps in detail. Step 1 is to specify that the userName field correspond to the mask rule:

       <form name="inputForm">            <field property="userName"                   depends="minlength,maxlength,mask">

This step is similar to the one you performed in the previous example. Now the userName is associated with three rules: minlength, maxlength, and mask.

In step 2, you specify an error message key for the mask rule. Because a generic message for a mask rule would not make sense, you need to specify an error key for this rule using the msg element as follows:

           <form name="inputForm">                <field property="userName"                       depends="minlength,maxlength,mask">                     <msg name="mask"                          key="inputForm.userName.mask"/>

The msg element takes two attributes. The name attribute specifies which rule you want to associate the message key with. The key element specifies a key for the message in the resource bundler.

Now that you have specified the key, step 3 is to add the message to the resource bundle:

 inputForm.userName.mask={0} must start with a letter and contain only letters, numbers and underscores

Notice how specific this error message is. Essentially, you are describing what the regular expression does in plain English (or French, or whatever languages you plan on supporting). You can see how the message has to change each time you use the mask rule with other fields. For example, the message for a mask rule applied to a phone number is going to be very different from a message for a mask rule applied to a Zip code.

Finally, in step 4 you configure the value of the mask variable to a pattern that implements your business rules. The mask variable of the mask rule contains the regular expression that you want to apply to the field. If the field does not match this rule, then it will not validate. Here is the mask for our userName field:

      <var>           <var-name>mask</var-name>           <var-value>^[a–zA–Z]{1}[a–zA–Z0–9_]*$</var-value>      </var>

Regular expressions are a necessary weapon in your developer arsenal. For the regular expression neophytes, the ^ specifies that we want to match the start of the line. Thus, ^[a–zA–Z]{1} means that we expect the first character to be an uppercase or lowercase letter. The {1} means we expect one of the items in the list. The expression [a–zA–Z0–9_]* specifies that we expect many (zero or more) letters (a–zA–Z), numbers (0–9), and underscores (_) after the first character. You could change the * to a {10}, which would mean that you expect 10 characters after the first character, and then you would not need the maxlength rule. However, the error messages are clearer if you can split them up among rules--for example, the error message for maxrule would be more specific than the error message for mask.

Our example code that uses regular expressions is shown in full in Listing 12.4.

Listing 12.4: Sample code using regular expressions.

           <form name="inputForm">                <field property="userName"                       depends="minlength,maxlength,mask">                     <msg name="mask"                          key="inputForm.userName.mask"/>                     <arg0 key="inputForm.userName"/>                     <arg1 key="${var:minlength}"                           name="minlength" resource="false"/>                     <arg1 key="${var:maxlength}"                           name="maxlength" resource="false"/>                     <var>                          <var-name>minlength</var-name>                          <var-value>5</var-value>                     </var>                     <var>                          <var-name>maxlength</var-name>                          <var-value>11</var-value>                     </var>                     <var>                          <var-name>mask</var-name>           <var-value>^[a–zA–Z]{1}[a-zA-Z0-9_]*$</var-value>                     </var>                </field>           </form>

What if you want to use the same mask on more than one form? For example, the registration form and the login form will both have usernames on them. In the next section, we look at a way to globally define constants that you can reuse.

< Day Day Up >