How To Use The Struts Validator Plug-in with Oracle JDeveloper 10g

An Oracle JDeveloper How To Document
Duncan Mills
January 2004

Contents

      Introduction
      Setting up a project with the Validator plug-in
      Using Validator with ADF model bound pages
      Validation Precedence
      Conclusion

Introduction

This document discusses how you can set up a project in Oracle JDeveloper 10g to use the Validator plug-in provided with Apache Struts. The Struts Validator is an extension to Struts which allows you to define declarative input validation using rules defined in XML, rather than having to code Form Beans with custom validation code. This in turn can mean that there is less requirement to code specialized Form Beans for handling page input, as the Validator can be successfully used with dynamic Form Beans, defined wholly in XML, using the Struts DynaActionForm .

The Validator plug-in is supplied with a predefined set of commonly used validation rules such as Required, Minimum Length , Maximum length , Date Validation , Email Address validation and more. This basic set of rules can also be extended with custom validators if required.

The Validator plug-in has two modes of operation. It will validate form input as the Form is submitted to the Struts servlet, and yet it also has the capability to carry out "instant" validation using JavaScript in the browser as the user enters or updates data. This can help the site designer to create a highly interactive application in a simple declarative way.

 

Setting up a project with the Validator Plug-In

Using the Validator plug-in with Oracle JDeveloper 10g is a relatively straightforward task. The setup involves the following steps:

  1. Add the Validator plug-in to your struts-config.xml file
  2. Copy the Validator rules file into your project
  3. Copy the predefined Validator error messages into your resources file
  4. Setup Form Beans to use the correct superclass
  5. Define your validation rules usage for the relevant Form beans
  6. Alter pages that need JavaScript validation

Note that if you are retrofitting a Struts application to use the Validator plug-in you will have to make changes to the superclasses of existing Form Beans that you wish to be processed by the Validator (see Step 4 for the new superclasses you will need to use).

1. Add the Validator Plug-in to the struts-config.xml

The Validator plug-in can be added to the Struts XML configuration file manually by editing the XML or by use of the Structure pane and property inspector. Using the Structure pane carry out the following steps:

  1. In the application navigator select the struts-config.xml file
  2. In the structure pane, right click on the the top level Struts Config node and choose New > Plug In from the context menu. This will create a new plug-in node in the structure.
  3. Select the new plug-in node and switch to the property inspector
  4. Set the className property for the plug-in to org.apache.struts.validator.ValidatorPlugIn
  5. Now with the plug-in node still selected in the structure pane bring up the context menu and choose New > Set Property. This will create a child node under the plug-in labeled as <set-property>.
  6. Select the new <set-property> entry and switch to the property inspector.
  7. Set the property property for this <set-property> entry in the inspector to pathnames
  8. Set the value property to the following (this can be changed to suit your application):
    /WEB-INF/validator/validator-rules.xml,/WEB-INF/validator/validations.xml

This value entry for the pathnames property defines a comma separated list of XML files. The first file mentioned (validator-rules.xml) defines the reusable validation definitions that your application will use. The second file (validations.xml) will be used to define the usages of those rules. As you enable validation for individual forms, it is this second file which you will be updating. Both of these files need to be stored under the WEB-INF directory, in this case they've been placed in a validator sub directory to keep things neat.

If you now look at the underlying XML for the Struts configuration you will see an entry something like this:

 <plug-in className="org.apache.struts.validator.ValidatorPlugIn">
     <set-property property="pathnames" 
                               value="/WEB-INF/validator/validator-rules.xml,/WEB-INF/validator/validations.xml"/>
 </plug-in>

2. Copy the Validator rules file into your project

When defining the plug-in we specified the use of a rules file called validator-rules.xml which has to be placed in the /WEB-INF/validator directory. The basic version of this file is supplied with JDeveloper and can be copied from it's location in %JDEV_HOME%/jakarta-struts/lib/validator-rules.xml, into your project at the location that you've chosen. This is the file you will customize if you need to add any specific rules of your own to the framework. If you just need to use the standard rules, the file will not need changing. The DTD for the validator-rules file is also available in the same /lib directory.

3. Copy the predefined Validator error messages into your resources file

The standard Validator rules require certain string resources to be present in your resource file(s) e.g. ApplicationResources.properties. These standard error messages are all listed at the top of the supplied validator-rules.xml and should be copied into your properties file. Here is a list of the predefined strings:

# Struts Validator Error Messages
errors.required={0} is required.
errors.minlength={0} can not be less than {1} characters.
errors.maxlength={0} can not be greater than {1} characters.
errors.invalid={0} is invalid.

errors.byte={0} must be a byte.
errors.short={0} must be a short.
errors.integer={0} must be an integer.
errors.long={0} must be a long.
errors.float={0} must be a float.
errors.double={0} must be a double.

errors.date={0} is not a date.
errors.range={0} is not in the range {1} through {2}.
errors.creditcard={0} is an invalid credit card number.
errors.email={0} is an invalid e-mail address.

The actual values of the error strings can of course be edited to suit your requirements. If you want to alter the message keys (e.g. errors.required to validator.errors.required) then be sure to update the matching msg attributes within the validator-rules.xml files.

4. Setup Form Beans to use the correct superclass

The basic Validator setup is now done. All the changes from now on involve the actual implementation of the plug-in functionality. The most significant difference from normal Struts operations is in the superclass used for your Form Beans. A normal Struts Form Bean will be based on either the ActionForm or DynaActionForm classes for statically defined or dynamic form beans respectively. If you want to validate the input to a Form Bean using the validator plug-in you have to instead use one of the following superclasses.

  • For static (coded) Form Beans
    • org.apache.struts.validator.ValidatorForm
    • org.apache.struts.validator.ValidatorActionForm
  • For dynamic (declarative) Form Beans
    • org.apache.struts.validator.DynaValidatorForm
    • org.apache.struts.validator.DynaValidatorActionForm

You'll notice that there are two possible superclasses for each type of Form Bean. These come into play when several Forms reuse the same underlying Form Bean. The ValidatorForm / DynaValidatorForm superclass should be used when all usages of a Form Bean need to share the same validation rules. The ValidatorActionForm / DynaValidatorActionForm superclass should be used when different rule sets need to applied to a Form Bean depending on the Action that is consuming it.

If you are using ADF Model databound pages then you also have to use a separate superclass for it's Form Bean. This is discussed in the Data Pages and Validator section below.

5. Define your validation rules usage for the relevant Form beans

Now comes the moment to actually implement some validation. The usage of the rules are defined in the /WEB-INF/validator/validations.xml file, below is a simple example of such a rule usage which defines validations for a simple input form with two fields, emailAddress and password. The emailAddress field has two rules applied to it, required and email, which will ensure that the field is entered and that the value that is entered is a string in the correct format for an email address. The password field only has the required rule applied:

<?xml version='1.0' encoding='windows-1252'?>
                              

<form-validation>
                              

  <formset>
                              

    <form name="logonBean">
                              

      <field
                              

        property="emailAddress"
                              

        depends="required,email">
                              

        <arg0 key="logon.email.validation"/>
                              

      </field>
                              

      <field
                              

        property="password"
                              

        depends="required">
                              

        <arg0 key="logon.password.validation"/>
                              

      </field>
                              

    </form>
                              

  </formset>
                              

</form-validation>
                            

The name attribute of the <form> element either refers to the name of the Form Bean that is being validated, or to the Action which the bean is associated with depending on what superclass you used for the Form Bean. The <arg0> elements used in both field definitions are keys to strings that will be used in any error message that gets generated.

Once you have registered validations in the validations.xml file you should also set the input attribute of any Actions in the struts-config that are effected. The input attribute is used by the Validator framework to work out what page to redirect to to display the relevant validation errors. Make sure that those pages already contain an <html:errors/> tag so that the errors raised by the Validator can be displayed.

6. Alter pages that need JavaScript validation

If you want to use the JavaScript driven "instant" validation features of Validator, you will have to make some slight changes to the relevant pages.

  1. In the <head> section of the page add the <html:javascript /> tag. This has a formName attribute which will name the <form> element from the validations.xml that this page needs to use to apply validation rules. At runtime the tag assembles the correct JavaScript fragments for use by the various field validations. Using the example validations.xml above the tag would read:
    <html:javascript formName="logonBean"/>
  2. In the <html:form> tag on the page add a onSubmit handler for the Form. This can be done through the property inspector for the <html:form> tag. This handler has to call a method which contains the name of the relevant<form> element in the validations.xml file, in the case of the example here the code would be:
    <html:form action="/processLogon.do" onsubmit="return validateLogonBean(this);">
    The name of the method to call is generated from the keyword "validate" prepended to the <form> element name,

If you run the page having added the above changes and see JavaScript in the body of the page then the problem is due to a mismatch in the value you have applied for the formName attribute of the <html:javascript> tag and the name used in the validations.xml

Using Validator with ADF model bound pages

So far, this how-to has discussed the use of Struts Validator with normal Struts pages and Form Beans. However, you can also use the Validator to enhance pages that use the ADF model for data binding to your business service.

Data bound pages can either be handled by a DataPage action (type oracle.adf.controller.struts.actions.DataForwardAction) or can be a conventional page with an associated DataAction (type oracle.adf.controller.struts.actions.DataAction). Both operate and are configured in the same way, using a UIModel.XML file which describes to the ADF Model framework what data is bound to the page.

When you create a data bound page, JDeveloper automatically creates a Form Bean called DataForm in your Struts configuration. This is a generic dynamic Form Bean that the ADF model uses in conjunction with the UIModel.xml file to handle input from a bound page. You can use the Validator with this Form Bean "as is" but only the JavaScript validation capabilities of the plug-in will work in that case.

In order to use the full scope of validation functionality with a data bound page you need to carry out the following steps:

  1. Create a new Form Bean in the Struts configuration either by using the context menu in the structure pane or by editing the XML.
  2. Set the type attribute of the Form Bean to oracle.adf.controller.struts.forms.BindingContainerValidationForm
  3. Set the className attribute of the Form Bean to oracle.adf.controller.struts.forms.BindingContainerValidationFormConfig
  4. There is no need to define <form-property> elements for the Form Bean, but you do need to add a <set-property> tag which defines the UIModel used by this data bound page e.g.
    <set-property property="modelReference" value="myUIModel"/>
    You can copy this <set-property> element from the DataAction or DataPage itself which will hold the same reference. This allows the Form Bean to understand the fields which are available for validation on this particular screen.
  5. Bring up the property inspector for the DataPage or DataAction and change the name property from "DataForm" to the name of the new Form Bean you have just created
  6. Likewise set the input attribute for the Action to point at the associated JSP. This is an important step because it tells the Validator plug-in where to forward to if there is a validation failure.
  7. Set the page up for JavaScript validation if required (see the section on JavaScript validation earlier in this document)
  8. Finally edit your validations.xml file to add the rules you require for this page. Use the name of your new Form Bean as the name attribute of the <form> tag and the names of the fields as defined in the associated UIModel.xml file.

The following is an example of the various elements used to Validator enable a DataPage called /maintainUserRecord.do

The Form Bean

    <form-bean
                              

       name="userRecordValidatorBean"
                              

       type="oracle.adf.controller.struts.forms.BindingContainerValidationForm"
                              

       className="oracle.adf.controller.struts.forms.BindingContainerValidationFormConfig">
                              

          
                               <set-property property="modelReference" value="maintainUserRecordUIModel"/>
                              

    </form-bean>
                            

Notice how the Form Bean has a <set-property> element which is the same as the associated /maintainUserRecord action.

The Action Definition

   <action
                              

       path="/maintainUserRecord"
                              

       type="oracle.adf.controller.struts.actions.DataForwardAction"
                              

       name="
                               userRecordValidatorBean"
                              

        
                               input="/adminPages/UserRecord.jsp"
                              

       parameter="/adminPages/UserRecord.jsp"
                              

       className="oracle.adf.controller.struts.actions.DataActionMapping" >
        <set-property property="modelReference" value="maintainUserRecordUIModel"/>
                              

        <forward name="save" path="/maintainUserList.do"/>
                              

        <forward name="newUser" path="/createNewUser.do"/>
                              

   </action>
                            

Once the new Form Bean is defined the only changes required to the Action definition are to change it to use the new bean (using the name attribute) and to set the input attribute to the correct JSP.

Enable Page for JavaScript Validation (if required)

   <html>
                              

       <head>
                              

         <title>...</title>
                              

          
                               <html:javascript formName="userRecordValidatorBean"/>
                              

       </head>
                              

       <body>
        ....
                              

         <html:form action="/maintainUserRecord.do"  
                               onsubmit="return validateUserRecordValidatorBean(this)">
                              

          ...
         </html:form>
      </body>
                              

   </html>
                            

To enable JavaScript validation on the page add both the <html:javascript/> tag and the correct onsubmit event to the form.

The Validation Rules

<form-validation>   
  <formset>
                              

     <form name="userRecordValidatorBean">
                              

        <field
                              

            property="LastName"
                              

            depends="required">
                              

              <arg0 key="global.lastName.validation.error"/>
                              

        </field>
                              

        <field
                              

            property="EmailAddress"
                              

            depends="required,email">
                              

              <arg0 key="global.email.validation.error"/>
                              

        </field>
                              

     </form>
                              

   </formset>
                              

</form-validation>
                            

Validation Precedence

When using the Validator plug-in with the ADF model, the plug-in will have the first bite at validating the input. If duplicate rules are defined in the Validator plug-in and in the underlying business service, the validator plug-in will be the one to process the rule. Likewise if the validator is set up to use JavaScript validation, then the JavaScript application of the rules will do the processing (if the client browser has JavaScript enabled). If any of the Validator plug-in defined rules are failed then the input is never sent to the ADF model for processing so rules defined with in the business service are not applied in that circumstance. Validations from the underlying business model will only be applied, once all the Validator plug-in defined rules have all been passed.

Conclusion

The Struts Validator plug-in provides a powerful and convenient mechanism for adding validation to your JSP applications. Implementing Validator within a Oracle JDeveloper 10 g project is straightforward and the declarative capabilities of Validator coupled with DynaActionForms mean less code and simpler maintenance for your applications.

drmills v1.2 05-Jan-2004

false ,,,,,,,,,,,,,,,