Package net.sf.jguiraffe.transform

The transform package contains interfaces and classes for transforming and validating data.

Form processing always includes the validation of the data entered by the user. If input is valid, it has to be copied into the application's data model. This step may require the conversion of data into some other types to conform with the types used within the model.

This package deals with both of these use cases. It defines the Transformer interface for data conversion and the Validator interface for validation. There are also fully functional implementations of these interfaces for the most common use cases.

It is also possible to implement custom transformers and validators. The interfaces are straight forward and easy to implement. When defining a form using the GUI builder the transformers and validators to use can be specified.

The Form class representing an input form in this framework implements some functionality for processing data entered by the user. It first invokes all registered validators on the input components. Only if this step was successful, the transformers are invoked. This causes the data entered by the user to be converted as necessary and copied into the bean associated with the form.

If a validator finds out that an input field contains invalid data, it returns a ValidationResult object with one or more error messages. Each message consists of a key that is specific for this kind of error message and a text to be displayed to the user. This text can contain further information about the error and how to resolve it (e.g. something like "This field must contain a number less than 100"; note that dynamic data depending on the validator's configuration is automatically added). In the documentation of each validator class the possible error messages are listed.

In addition to the key and the message a ValidationResult object also contains a level. The default level is ERROR indicating the input is actually invalid. It is also possible to use the level WARNING, which means that the input will be accepted, but may cause problems. Whether a validator produces error or warning messages can be configured with properties in the TransformerContext. For more information refer to the documentation of DefaultValidationMessageHandler.

Changing the error messages for certain or all validators is an often required use case. Per default error messages are obtained from the resource manager: the key of the error message is used as resource ID, as resource group the reserved name "validators" is used. The framework is shipped with default error messages in a couple of supported languages. If a specific language you need is not supported, you can add your own bundle for this language. To override specific validation error messages there are the following options:

• When a validator is defined in a builder script (in the body of the definition of the associated input component), properties can be set for this validator. In addition to configuration properties that affect the behavior of this validator, its error messages can also be defined. This can be done by using the key of the error message (as defined in the documentation of this validator) and assigning the new error text to it as the property's value. By making use of the <localizedProperty> tag, the new error message can be obtained from the application's resources. With this approach the error message for a specific input field can be adapted.
• To change a certain error message globally, another approach is better suited: Internally error messages for validation errors are obtained from an implementation of the ValidationMessageHandler interface. With DefaultValidationMessageHandler the framework provides a default implementation of this interface. The implementation to use is defined in the application's bean definition, by a bean named "validationMessageHandler". This bean definition can be overridden by an application to modify properties of the default message handler or even inject a completely different implementation. DefaultValidationMessageHandler allows setting a number of resource groups, in which it searches for the resources for error messages. So you can create your own resource group for error messages, which contains only resources for the error messages you want to change. If a message cannot be resolved in one of these groups, the default group for error messages is used. Refer to the documentation of DefaultValidationMessageHandler for a full description of all supported properties. By providing your own implementation of the ValidationMessageHandler interface you are free to implement an arbitrary strategy for obtaining error messages.

$Id: package.html 205 2012-01-29 18:29:57Z oheger $

Interface Summary

Interface	Description
Transformer	Definition of the Transformer interface.
TransformerContext	Definition of an interface for accessing data needed by transformers.
ValidationMessage	Definition of an interface describing a validation message.
ValidationMessageHandler	Definition of an interface for a central instance that manages validation messages.
ValidationResult	An interface that defines the results of a validation process.
Validator	Definition of a validator interface.

Class Summary

Class	Description
AbstractDecimalTransformer<T extends Number>	A base class for number transformers that operate on floating point numbers.
AbstractIntegerTransformer<T extends Number>	A base class for number transformers that operate on integer numbers.
ChainValidator	A special Validator implementation that allows combining multiple primitive validators.
DateTimeTransformer	A specialized transformer that transforms strings into date objects with both a date and time component.
DateTransformer	A specialized transformer that transforms strings into date objects.
DateTransformerBase	An abstract base class for date transformer objects.
DefaultValidationMessageHandler	A default implementation of the ValidationMessageHandler interface.
DefaultValidationResult	A default implementation of the ValidationResult interface.
DefaultValidationResult.Builder	A builder class for creating instances of DefaultValidationResult.
DoubleTransformer	A specialized number transformer implementation that deals with numbers of type java.lang.Double.
DummyTransformer	This class provides dummy implementations for the Transformer and the Validator interfaces.
FloatTransformer	A specialized number transformer implementation that deals with numbers of type java.lang.Float.
IntegerTransformer	A specialized number transformer implementation that deals with numbers of type java.lang.Integer.
LongTransformer	A specialized number transformer implementation that deals with numbers of type java.lang.Long.
NumberTransformerBase<T extends Number>	An abstract base class for transformers and validators for numbers.
RegexValidator	A specialized Validator implementation that uses regular expressions to validate user input.
RequiredValidator	A specialized Validator implementation that checks whether data was entered in mandatory fields.
TimeTransformer	A specialized transformer that transforms strings into date objects, taking only the time portion into account.
ToStringTransformer	A generic Transformer implementation that transforms arbitrary objects into formatted strings.
TransformerContextPropertiesWrapper	A specialized implementation of the TransformerContext interface that allows wrapping an existing context and extending its properties.
ValidationMessageConstants	This class defines constants for the keys of validation messages.

Enum Summary

Enum	Description
ValidationMessageLevel	An enumeration class that defines possible levels for validation messages.