edu.nrao.sss.validation
Class ValidationManager

java.lang.Object
  edu.nrao.sss.validation.ValidationManager

public class ValidationManager
extends Object

The entry point for validating model objects.

Most clients need use only the validate(Object, ValidationPurpose) method. A typical usage pattern is:

   ValidationManager myMgr = new ValidationManager();
   
   if (!myMgr.validate(newCar, ValidationPurpose.CERTIFY_READY_TO_USE))
     communicate(myMgr.getFailures());

Two Different Failure Lists
In the original implementation this class had one list of failures. If the validate method returned true (i.e., success), the getFailures() list would be empty. If it returned false, it would contain one or more validation failures. This can cause problems, though, when the only failures in the list are those that are not intended for display.

To remedy this problem, this manager now holds two lists of failures -- one for displayable failures and one for nondisplayable failures. If the validate method returns true, both of these lists will be empty. However, if it returns false, one, the other, or both may have failures, with a minimum of one failure in the combined lists. This means that clients, upon seeing a false return value, must now see if there are any displayable failures before committing to interaction with the user.

How the Manager Finds Validators
The ValidationManager finds a validator for an instance of a given target validation class by either referring to a validator registered by one of its clients or by relying on its default search mechanism.

Clients may use one of two methods to register validators for a particular class of validation target: registerValidator(Class, Class) and registerValidator(Validator, Class). The first method associates a class of validator with the class of validation target. The first time such a target is to be validated, the manager instantiates an instance of the validator class and uses it. It will use that same instance each time validation is requested on that class of validation target, unless the unregisterValidator(Class) method has been called on that class of validation target, or if a specific validator has been specified via the second method. This second method associates a particular instance of a validator with the given class of validation target. This validator may have been preconfigured by the client in some special way. The manager will continue to use that validator until either the unregister method is called or a new instance of a validator is registered.

If there is no instance or class of validator associated with a class of validation target, the manager will create and use a validator based on this naming convention: if the class of the validation target is abc.def.PqrStu, the validator class sought is abc.def.PqrStuValidator. If this class cannot be instantiated, the same logic will be applied to the superclass of abc.def.PqrStu until a validator is found. If a validator cannot be found for any of the classes on the inheritance tree, the return value of the validate method will be false and the list of failures will contain one failure that notes the lack of validator for the validation target class.

Version Info:

$Revision: 1707 $

$Date: 2008-11-14 10:23:59 -0700 (Fri, 14 Nov 2008) $

$Author: dharland $

Since:

2007-02-02

Author:

David M. Harland

Constructor Summary

ValidationManager()
Creates a new instance.

Method Summary

List<ValidationFailure>	getFailures() Returns a copy of the list of displayable validation failures triggered by the most validation.
List<ValidationFailure>	getNonDisplayableFailures() Returns a copy of the list of nondisplayable validation failures triggered by the most validation.
Validator	getValidator(Class<?> targetClass) Returns the validator that this manager will use for objects of type targetClass.
void	registerValidator(Class<? extends Validator> validatorClass, Class<?> targetClass) Configures this manager to validate instances of targetClass with an instance of validator.
void	registerValidator(Validator validator, Class<?> targetClass) Configures this manager to validate instances of targetClass with validator.
Validator	unregisterValidator(Class<?> targetClass) Unregisters the validator associated with targetClass.
boolean	validate(Object target, ValidationPurpose purpose) Validates the target object for the given purpose.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ValidationManager

public ValidationManager()

Creates a new instance.

Method Detail

validate

public boolean validate(Object target,
                        ValidationPurpose purpose)

Validates the target object for the given purpose.

If all tests were passed, this method returns true. If this method returns false, the list returned by getFailures() will contain one or more ValidationFailures.

Parameters:

target - the object to be validated.

purpose - the reason for the validation. Different purposes trigger different validations and/or different levels of the same validations.

Returns:

true if target passed all the tests required for the given purpose, false otherwise.

registerValidator

public void registerValidator(Validator validator,
                              Class<?> targetClass)

Configures this manager to validate instances of targetClass with validator.

Note that this manager will hold a reference to validator. This means that any changes made to it after calling this method will be reflected in this object. This same validator will be returned via the getValidator(Class) method.

If either parameter is null, this method does nothing.

Parameters:

validator - the validator to use on instances of targetClass.

targetClass - the type of objects on which to use validator.

registerValidator

public void registerValidator(Class<? extends Validator> validatorClass,
                              Class<?> targetClass)

Configures this manager to validate instances of targetClass with an instance of validator.

The next time a validator is needed of an object of type targetClass a new instance of validatorClass will be created and used.

If either parameter is null, this method does nothing.

Parameters:

validatorClass - the type of validator to use on objects of type targetClass.

targetClass - the type of objects on which to use an instance of validatorClass.

unregisterValidator

public Validator unregisterValidator(Class<?> targetClass)

Unregisters the validator associated with targetClass. After this call no validator instance or validator class will be associated with targetClass.

Parameters:

targetClass - a class of objects subject to validation.

Returns:

the validator registered for use with instances of targetClass prior to calling this method. If no validator or validator class had been so registered, null is returned.

getFailures

public List<ValidationFailure> getFailures()

Returns a copy of the list of displayable validation failures triggered by the most validation. This list contains only those failures that can be shown to external users, it excludes failures that have no displayable message.

Returns:

a copy of the list of displayable validation failures triggered by the most recent validation.

See Also:

getNonDisplayableFailures()

getNonDisplayableFailures

public List<ValidationFailure> getNonDisplayableFailures()

Returns a copy of the list of nondisplayable validation failures triggered by the most validation. This list contains only those failures that have no displayable message. These failures should, though, have a debug message.

Returns:

a copy of the list of nondisplayable validation failures triggered by the most recent validation.

See Also:

getFailures()

getValidator

public Validator getValidator(Class<?> targetClass)

Returns the validator that this manager will use for objects of type targetClass.

The validator returned is the one actually held by this manager. This means that if you alter the properties of the returned validator, those changes will be reflected in this manager. If this manager holds no validator for targetClass, it traverses the target class's hierarchy tree to the top. If no validator is found for any of the superclasses, null is returned.

Parameters:

targetClass - the class of object for which a validator is desired.

Returns:

a validator for targetClass, or null if this manager cannot find one.