API User Guide

Introduction

One of the motivations for building iScreen is to have as simple of an API as possible, pushing the bulk of the complexity into configuration files. This guide is meant to describe how to use the API within your application. It describes the interface to the individual validation services, as well as the APIs to the validation exceptions that are thrown (and the failures they contain).

Validation Service Interface

An instance of the org.iscreen.ValidationService interface provides the ability to execute a validation. The validate() method provides this capability and throws an org.iscreen.ValidationException. The validate() method takes as a parameter the Object that is to be validated. Typically, this Object is a JavaBean (though that is not a requirement). The configuration file maps properties and data from this Object to the set of Validators that act upon this map (note that the Validator typically doesn't access this Object directly). The configuration of those Validators are handled in the configuration file.

The ValidationService also provide a validateObject() method that works the same as the validate() method. It throws an unchecked exception, instead.

Documentation of validation rules can be retrieved from the ValidationService interface, as well. Assuming that the configuration of the validators contains documentation (the doc tag), then calling the getDocumentation() method will return an iterator over all documentation elements within the configured validation set.

Validation Exceptions

The exception thrown by calling the validate() method on the ValidationService is a checked exception. There is a bit of a debate in best practices circles on whether exceptions of this nature should be checked or unchecked. It is the opinion of the author that these should be checked; hence, the org.iscreen.ValidationException is a checked exception.

If a checked exception is inappropriate for your needs, the validateObject() method is effectively identical to the validate() method with the primary difference being that a failure throws an unchecked exception called org.iscreen.ObjectValidationException. This exception contains the same information as the ValidationException with one primary difference: the underlying engine uses ValidationException, with the validateObject() method catching that exception and rethrowing the ObjectValidationException. This means that the original stack trace is not a part of the ObjectValidationException, but is a part of its root cause exception (a ValidationException). Normally, application developers don't need that root cause exception unless they're debugging, so it shouldn't cause too many difficulties.

The primary purpose of the exception is to provide a method for catching a failure during validation (a valid business failure). In addition, it acts as a container of the failure messages (the details of the failure or failures).

Failures are retrieved from the exception via several methods (getFailures(), getFailureMessages(), etc.). Failures have a severity level and can be retrieved based upon their severity using the getFailures() methods, either by a minimal severity level (to ignore warnings) or by providing a range, from minimum to maximum severity level.

From the exception, two types of messages can be retrieved. One simply returns the messages as Strings (with no additional context). This is the getFailureMessages() (or getWarningMessages()) method. The getFailures() (or getWarnings()) method returns a List of objects of type org.iscreen.ValidationFailure, which, in addition to providing access to the String message, contains some additional context about the failure.

Validation Failures

The org.iscreen.ValidationFailure class is used to contain an individual failure message as well as the context around that failure. It is designed to be used to link the failure message to some User Interface component or presentation-layer field.

The getMessage() method returns the actual String message. Named messages can also be retrieved using the getMessage() method by passing in the configured name. This method maps to the 'msg' element in configuration (the 'msg' element is a sub-element of the 'failure' element). The getLabel() method provides access to the configured Validator's label (this is found in the configuration file). In addition, there are a few other methods that provide access to fields and indexes (when used within a looping configuration).

The getSeverity() method returns an int that represents the configured severity of the underlying failure message (the default value is 5, or the constant ValidationFailure.FAILURE).

The label is the primary link between the message and some UI component. It is specified within the configuration file and can be localized.

There is also a getTrace() method that will return a ValidationTrace object, which represents the trace through the configuration from the validation set (i.e. ValidationService) through to the fields being validated. Two types of traces are available: trace through service id to service id to validator, and a field trace, which traces from service id to any 'mapped service' through mapped fields in validators (i.e. whereever there is a mapping, the field trace will reference it in the trace).