wst validation
validation api overview
Vijay Bhadriraju
IBM Rational
January 22, 2005
Intoduction
 

The following document provides a overview of the validation interfaces and the classes used in WTP.

Overview
 
 
 
IValidator
An implementation of this interface validates a model. [Details]
IReporter
The IReporter is the interface through which the IValidator interacts with the user to report problems, report status, and receive cancellation requests. [Details]
IHelper
An IHelper is a loading mechanism for an IValidator. The IHelper separates the IValidator from its environment, every model that the IValidator validates is retrieved by the IHelper implementation. [Details]
IMessage
The IMessage is the Locale-independent message that the IValidator uses to report a problem to the user. [Details]
IFileDelta
When the validation is launched, the framework directs validators to perform full or incremental validation through IFileDelta instances. An IFileDelta instance represents an object, usually a file, that has changed on the user's system and needs to be revalidated. If no IFileDelta instances are passed to the IValidator, the validator should revalidate everything. [Details]
ValidationException
A ValidationException is one of two types of exceptions that the IValidator may propagate to the framework. A ValidationException contains an IMessage instance that will be reported to the user, and this exception may wrap another exception. [Details]
MessageLimitException
A MessageException is one of two types of exceptions that the IValidator may propagate to the framework. A MessageLimitException is thrown by the framework if the IValidator attempts to report a message when the maximum number of messages has already been reported. MessageLimitException does not contain an IMessage to be reported to the user. [Details]
 Convenience Classes
 

IValidator

 
IValidator is an interface that, when implemented, validates a model. A validator loads its model through an IHelper, traverses the model itself, and communicates with the user through the IReporter.

There is no more than one instance of a validator. Because each validator instance performs on the same type of model input, and performs the same rule checks against that input, no more than one instance of a validator is needed.

A validator can perform full or incremental validation. The caller's preferred type of validation is indicated by the value of the IFileDelta[] passed into the validate method. If the IFileDelta[] is null or empty, the caller wants full validation performed. Otherwise, the caller wants only those files named in the array to be validated. But a validator is not required to support incremental validation; it can ignore the IFileDelta[] if it wants to.

Because each validator must be environment independent, each file name must be independent of the environment. Since nothing can be done without some knowledge of the environment, the environment specific Helpers are used to convert the generic file names into environment specific objects, as necessary. But all of that is shielded from the validators.

When a validator adds a validation message, it identifies itself through a unique id; thus, when a particular's file's validation messages need to be removed (before incremental validation of that file begins), all messages associated with that file, by that validator, are removed. This ensures that validator A cannot modify or delete messages entered by validator B.

Every message shown to the user, whether it's the message in a ValidationException, or a validation error, will be displayed to the user. Validators do not display messages to the user other than validation messages and subtask messages. This is necessary for Locale-neutrality and environment-neutrality. If a catastrophic error occurs, from which the validator cannot recover, the validator should throw a ValidationException.

 

IReporter

 
The IReporter is an interface that is used for interaction with the user. IReporter can show validation messages, remove validation messages, display subtask messages, and get cancellation input from the user. Every validator uses an IReporter, and an IReporter can be used by many IValidator implementations.

Each IReporter implementation is customized for a particular environment; in Web Tools Project the IReporter reports validation messages via the task list. Generally, only one implementation of an IReporter is needed in an environment, unless the framework wishes to choose different optimization techniques based on the user's actions. For example, an incremental IReporter may need to cache messages, while a full IReporter can immediately send the output to the user. If a full validation is about to be performed, pass in the full IReporter for savings in memory and faster performance. If incremental validation is about to be performed, the framework can pass in the incremental IReporter to support addition and deletion of messages. Which type of reporter, full or incremental, is hidden from the IValidator. These optimizations are environment-specific and are handled by the framework.

 

IHelper

 
The IHelper interface that is the loading mechanism for an IValidator. This interface defines the method(s) that will load and initialize a particular type of model for an IValidator. A model is any object or group of objects that is either validated, or whose meta-data is required to validate another object or group of objects.

The IHelper separates the IValidator from its environment (UI verses Headless); the IValidator asks the IHelper to retrieve an object, and the IHelper implementation knows how to load the object for a particular type of environment. If running in WebSphere Studio, for example, the IHelper implementation should know how to convert file names into IFile types; if running outside of WebSphere Studio, a different IHelper implementation would convert the file name into a java.io.File type. Different IHelper implementations are shipped with each environment.

There need not be more than one instance of an IHelper because the mechanism for loading a type of model should not vary in a given environment.

IHelpers are not tied to a particular validator. Rather, IHelpers are mechanisms which can load a particular type of object in a particular environment. When IHelpers are independent of IValidators, then that IHelper can be reused by any validator which needs to load that particular model.

 

IMessage

 
IMessage represents a locale independent validation message. If an IValidator is running on a server, and the client is running on a different java.util.Locale than the server, then the validation messages must be presented in the client's locale, not the server's. To enable the message text to be presented in the client's locale, instead of adding text to the IReporter directly, the IValidator passes an IMessage to the IReporter.

The IMessage contains some required data and may contain some optional data.
Data Required (R) or
Optional (O)
Description
bundle R The name of the resource bundle category which contains the string. (A resource bundle category identifies the base name of the .properties file, e.g. "mymessages.properties", "mymessages_en_US.properties" both have the same resource bundle category: "mymessages"
messageId R The id of the message in the resource bundle; used to extract the message from the bundle.
parms O If the text needs runtime parameters substituted in, this array of strings contains the parameters. Otherwise, this array is null.
target object O If the message applies to a particular object (e.g. a file), this parameter identifies the object. Otherwise, this value is null.
severity R Identifies the severity of the message. This flag's value is one of the SeverityEnum constants.

 

IFileDelta

 
IFileDelta is used for incremental validation. An array of instances of this type is passed into the IValidator's validate method for processing. An IFileDelta contains two pieces of information: the name of the file which has changed, and an integer flag identifying the type of change (ADDED, CHANGED, DELETED). Given an IFileDelta, an IValidator can perform validation on just the file which has changed, and perform the type of validation necessary, as indicated by the IFileDelta's flag.
 

ValidationException

 
The only exception that an IValidator may create and throw is a ValidatorException. When the framework catches a ValidationException, the exception's IMessage will be extracted and shown to the user. If an IValidator catches an unexpected exception, instead of propagating that exception up to the framework, the exception should be wrapped in a ValidatorException and the ValidatorException should be propagated up to the framework.
 

MessageLimitException

 
If the framework imposes a limit on the number of validation messages which can be reported, then when that limit is reached, a MessageLimitException is thrown by the framework. IValidators should not catch the MessageLimitException; instead, they should let the exception propagate up to the framework and the framework will do whatever cleanup is necessary.
 

Convenience Classes

 
The validation framework provides, in addition to interfaces, some simple implementations of three interfaces: IFileDelta, IMessage, and IHelper. These classes are provided for convenience and it is not required that they be used.
  1. FileDelta
  2. Message
  3. PassthruHelper
The FileDelta class is provided as a simple way for frameworks to create the IFileDelta[] for the IValidator.

Message is provided so that IValidators can add validation messages, subtask messages, and ValidationException messages easily.

PassthruHelper is provided for environments which already have a EMF model loaded. Instead of implementing a loadModel method, the EMF object is set on the PassthruHelper, and its loadModel method merely returns the object with which it was initialized. Note that IValidators are not permitted to assume that a PassthruHelper is being passed to them; an IValidator must pass in a unique name of a model into the loadModel method, so that IHelpers which are not PassthruHelpers can identify the type of model which needs to be loaded. The PassthruHelper can be used only in the WAS environment.