Introduction

The jaev Framework is quite simple to use. On this page you'll find a brief introduction how the framework works, and how you might integrate it in you application.

Basic usage

Obtaining the libraries

Before you can start using the framework you will have to obtain the jaev libraries. The libraries may be downloaded on the Downloads page. If you are using the Apache Maven framework you can add the jaev framework as a dependency. You can find a brief guide for adding jaev to your Maven build in the jaev Wiki.

Creating a Validator

There is not much to do to use a jaev Validator. First you'll have to create a Validator instance. To create a very simple instance you'll may create it like this:

Validator validator = Validation.basic().fromAddress("example@your.domain").buildFactory().getValidator();

This call creates a BasicValidator with the from address "example@your.domain". If you decompose the call, you will get:

ValidatorFactoryBuilder builder = Validation.basic();
builder.fromAddress("example@your.domain");
ValidatorFactory factory = builder.buildFactory();
Validator validator = factory.getValidator();

The Validation class provides a couple of ValidatorFactoryBuilder. This builder class accepts configuration parameters for the Validator creation. Most of these parameters are optional and may be used for advanced configuration issues, but the from address is a mandatory parameter and must be specified.

Note: You also may use the public constructors if you want to do some really advanced stuff, i.e. play around with the thread pool executor service of the TimeoutCapableValidator.

Performing a validation

After obtaining a Validator instance performing a validation is almost more easy:

Result result = validator.validate("some.mailaddress@another.domain");

In the Result object you will have many informations about the success of the validation process. If the result code is ADDRESS_VALID the e-mail address is valid, which is the most simple result. Unfortunately the job is not finished by fetching the Result. This is why the result contains more informations than only the result code. A result consists of:

• A ResultCode to announce the details of the validation result.
• The information if the code is technically or logically motivated with the ResultCode.Type.
• The validity level from INVALID up to ACCESSIBLE.
• A category which shows in which part of the validation process the result code resides.
• A numerical identifier if you want to store or log the result.
• And some further Objects to create a human readable result message.

Interpret the result

So, why are the things in the jaev framework so complicated? If you take a look at the Commons Validator framework, the EmailValidator has only one relevant method: public boolean isValid(java.lang.String email).

The jaev framework was build to provide more detailed information. One the one hand it's my opinion that it is good design to provide detailed feedback to the user (i.e. to tell him that he might misspelled his top level domain). On the other hand the validation done with the jaev framework is far more complex so it has to deal with quite a lot more exceptional situations.

So how do you translate the complex Result state to a boolean? This is where the Acceptance comes into the game.

boolean valid = Acceptance.SIMPLE.accept(result)

The Acceptance interface defines strategies to accept a validation result as valid. At the moment there are three acceptance strategies pre defined. But you also may define your own.

Message creation

It's a quite common task to create user compliant messages after validation. At least when the result considered invalid. The Result class offers a getMessage or the toString method, but the messages issued there are quite technical.

The integration package offers the ResultTranslator interface and a simple implementation ()with the StandardMappingTransator) of this interface which translates the result into a string. So you may use a standard ResourceBundle for message retrival.

String code = resultTranslator.translate(validationResult);
ResourceBundle resourceBundle = ResourceBundle.getBundle(this.resourceBundleName, currentLocale);
String messageString = resourceBundle.getString(code);

It's also a quite nice pattern to create a MessageFormat from the messageString so you can use the additional items provided by the Result class for further formatting.

String message = new MessageFormat(messageString, resourceBundle.getLocale()).format(objects);

You can use the String.format(..) method if you prefer the printf style. If you are in a JSP/JSF (pre Java 5) environment it is often nicer to stick to one style to create the messages.