FormProc

Form Proccesing and Validation

Introduction

FormProc is a Java library designed to make web form handling easy. Forms are represented as objects which manage a collection of form elements. Submitted data can be validated through several mechanisms:

Requirements

FormProc requires JDK 1.2 or higher.

FormProc has been tested in the following Web servers:

FormProc should work with any web server which supports the Servlet API 2.2 or higher. FormProc can work with any application, not just web applications. See the feature list and example application below for more information.

Features

FormProc has the following features:

Use in Applications and Servlets
FormProc can be used in applications or servlets. The Form class accepts Lists or arrays of FormData while the HttpForm class extends the Form class to process HttpServletRequests.

XML Configuration
FormProc is configured using XML files. FormProc will monitor your configuration files and reload the configuration if the files are loaded. The configuration system includes support for an tag for including other XML configuration files. Note: if formproc.xml is loaded through the class loader then it will NOT be monitored...files specified in this file will be monitored though.

Validate using regular expressions, scripts, rules, or Java classes
Any class which extends from the Validator base class can be used to validate form data. In addtion validators can be configured with arbitrary configuration data.

Shared validators
Validators can be specified in the main FormProc configuration file and then reused through all forms. Validators can be overridden on an element by element basis.

Additional Validators can be added at deploy-time
Validators are specified in the main configuration file at deploy-time making it easy to additional validator types.

Nested validators using the 'group' validator
Group validator is a validator itself and can thus be nested within other group validators.

Validation on particular fields can be skipped
PassFormValidator allows validation to be explicitly skipped.

Form elements can be grouped together and validated as a group
Form element can be grouped together and validated using validators written as Java classes or scripts.

Extensible storage mechanism (Auto-poplulation of target objects)
The FormProc store system is completely pluggable to that alternative storing methods can be defined. FormProc includes two storers for immediate use: a ReflectionStorer which stores data in the target object using reflection and a storer which stores data in a Map.

Extensible error message system
FormElement messages and validator error messages provided by any class which implements the MessageProvider interface. Two implementations are already provided: the first uses inline messages and supports multiple languages. The second uses ResourceBundles for locating localized messages.

Extensible data conversion
Convert data provided by the form from one type to another using the built in type converters or write your own type converters. Included type converters handle standard type conversion such as numeric, boolean and date.

Examples

The FormProc distribution includes two examples which demonstrate how to use FormProc. The first example is a web application which demonstrates how FormProc can be used in a JSP-based web application. The second example is a Swing desktop application which shows how FormProc can be used in client-side Java applications.

Running the Example JSP Pages

Drop the formproc-example.war file into Tomcat's webapps directory and restart Tomcat.

Now load the index.jsp page in your web browser. You will see the messages specified in example-form.xml next to each field. Fill in the fields and click submit. If any field is invalid then you will go back to the index page and the fields will be filled in and an error message will be displayed. If all of the fields are valid then you will see a page stating that all fields are valid and all the values are displayed.

The example provided shows how each of the included validation methods work. The name field is validated using a regular expression which is defined as a shared validator. The age, username and password validators are included into the main configuration through the <include> tag. The password and passwordVerify fields are validated by a shared script validator which uses the PasswordValidator.py python script located in the WEB-INF/classes directory. The age field is validated by two validators in a group: the rule-based validator with the class org.formproc.example.IsIntRule class and a regular expression. These validators are defined as a shared validator in the main formproc.xml configuration file. Finally the username field is validated by the org.formproc.example.UsernameValidator class.

In addition to the idividual field validation, the example also demonstrates validation of a group of fields. The password and passwordVerify fields are grouped together and must be equal. The validation logic is provided by the FieldsMatch.py script in the WEB-INF/classes directory.

Finally, the example code demonstrates how type converters work by converting the birthdate field from a String to valid Date object.

Running the Example Application

To run the example application, either double-click the FormProc-example.jar or execute java -jar FormProc-example.jar.

Note that the configuration and validation logic for the example application is exactly the same as the web application example.

Resource Loader

FormProc utilizes the resource loader API from EdenLib to load form configurations. The default resource loader is the FileResourceLoader which is located in the com.anthonyeden.lib.resource package. If you use the default resource loader you do not need to specify it in the formproc.xml configuration file. EdenLib also provides a ClassPathResourceLoader which can be used to load resources from the Java class path.

You can easily add additional resource loaders by implementing the com.anthonyeden.lib.resource.ResourceLoader interface and specifying that loader as the value of the loader attribute in the formproc.xml configuration file.

Loaders may support the optional monitor flag. If a loader supports this flag then the resource should be reloaded if it is modified by calling the load(InputStream in) method in the ResourceRecipient interface.

Configuration

All FormProc configuration is done using XML configuration files. The following annoted configuration files explain how to configure FormProc. Also included are links to the DTDs for each of the configuration files.

JavaDocs

All FormProc source code includes JavaDoc comments.

Acknowledgements

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

Disclaimer

 
 THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, 
 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 
 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 
 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 POSSIBILITY OF SUCH DAMAGE.