Package net.sf.jguiraffe.gui.forms

Class Form

  • public class Form
extends Object

    This class represents a form.

    Instances of this class can be used to deal with forms, e.g. initializing the form's widgets with data obtained from a model object or validating the user's input. A Form object must be initialized with objects representing the form elements or fields. These objects are of type FieldHandler and contain all information needed for correctly handling GUI widgets and the data they may contain.

    An important functionality of this class is to enable data transfer between the form's fields and the properties of a model object. By properly initializing the FieldHandler objects with transformers and validators it can be assured that suitable validation and data conversion take place. Model objects are accessed through a BindingStrategy; therefore this class can collaborate with different types of model objects provided that a corresponding BindingStrategy implementation exists.

    After a Form object and its corresponding fields haven been initialized usage of this class is quite simple. To initialize the GUI widgets associated with this form call the initFields(Object) method and pass in a model object instance with the values for the fields. (Of course, this model object must be compatible with the BindingStrategy the form was initialized with.) To perform validation and read the user's input back into a model object the validate(Object) method can be used. This method invokes all registered validators, and if validation succeeds, the user input is converted into the correct types and transfered into the given model object.

    Implementation node: This class is not thread safe; instances should be accessed by a single thread only.

    Version:
    $Id: Form.java 205 2012-01-29 18:29:57Z oheger $
    Author:
    Oliver Heger

    • Constructor Detail

      • Form

        public Form​(TransformerContext ctx,
            BindingStrategy strat)
        Creates a new instance of Form and initializes it with all required helper objects.
        Parameters:
        ctx - the TransformerContext (must not be null)
        strat - the BindingStrategy (must not be null)
        Throws:
        IllegalArgumentException - if a required parameter is null

    • Method Detail

      • getTransformerContext

        public TransformerContext getTransformerContext()
        Returns the transformer context.
        Returns:
        the transformer context

      • getBindingStrategy

        public final BindingStrategy getBindingStrategy()
        Returns the BindingStrategy used by this form.
        Returns:
        the BindingStrategy

      • getFormValidator

        public FormValidator getFormValidator()
        Returns the form validator. This can be null if no specific form validator has been set.
        Returns:
        the object used for validating the form

      • setFormValidator

        public void setFormValidator​(FormValidator formValidator)
        Sets the form validator.
        Parameters:
        formValidator - the form validator

      • addField

        public void addField​(String name,
                     FieldHandler fld)
        Adds the specified field to this form. This method must be called for each field that should be managed by this form object.
        Parameters:
        name - the field's (internal) name
        fld - the field handler for this field

      • initFields

        public void initFields​(Object bean)
        Fills the form's fields with the properties of the passed in bean. This method can be used to initialize the form.
        Parameters:
        bean - the form bean; can be null, then this operation has no effect
        Throws:
        FormRuntimeException - if an error occurs when initializing a field

      • initFields

        public void initFields​(Object bean,
                       Set<String> names)
        Fills a sub set of the form's fields with the properties of the passed in bean. This method will iterate over all fields specified in the given set and initialize them from the corresponding properties of the specified bean. The set must contain only valid names of fields that belong to this form; otherwise an exception will be thrown.
        Parameters:
        bean - the form bean; can be null, then this operation has no effect
        names - a set with the names of the fields to be initialized
        Throws:
        FormRuntimeException - if a field cannot be initialized
        IllegalArgumentException - if the set is null

      • validate

        public FormValidatorResults validate​(Object model)
        Validates this form and writes its content into the specified model object if validation is successful. This method performs validation on both the field and the form level. The former validation ensures that all fields contain syntactically correct data, i.e. the data they contain can be converted to their expected data type (e.g. the string entered by the user is indeed a valid date). The latter validation takes the form as the whole into account. Here for instance relations between fields can be checked (e.g. the date of delivery is greater than the shipment date). The passed in model object is populated with the form's data when all validation steps succeed. It must be compatible with the BindingStrategy used by the form. It is modified only if validation is successful; otherwise it is not changed.
        Parameters:
        model - the model object in which to write the form fields; can be null, then no data is copied
        Returns:
        an object with validation results

      • getFieldNames

        public Set<String> getFieldNames()
        Returns a set with the names of all defined fields.
        Returns:
        a set with the field names

      • getField

        public FieldHandler getField​(String name)
        Returns the FieldHandler object for the field with the given name. If no such field exists, null is returned.
        Parameters:
        name - the name of the desired field
        Returns:
        the field handler for this field

      • getDisplayName

        public String getDisplayName​(String fldName)
        Returns the display name for the specified field. This implementation checks whether a display name is explicitly defined for the field handler with the given name. If this is the case, it is returned. Otherwise the field's name is returned. If the field is unknown, null is returned.
        Parameters:
        fldName - the name of the field
        Returns:
        the display name for this field

      • getComponentStore

        public ComponentStore getComponentStore()
        Returns the component store of this form. In this object all components that belong to this form are stored.
        Returns:
        the component store of this form

      • validateFields

        public FormValidatorResults validateFields()
        Validates the fields of this form. This method ensures that all form fields are syntactically and semantically correct, i.e. it performs validation on both the fields and form level. After this method has been called and returned a positive result, the form bean is available and contains the current data.
        Returns:
        an object with results of the validation

      • validateFields

        public FormValidatorResults validateFields​(Set<String> names)
        Validates a sub set of the fields of this form. This method works like the overloaded version, but only fields whose name is contained in the passed in set are taken into account. This is useful if a partly validation is to be performed. If the set contains an invalid field name, a runtime exception will be thrown.
        Parameters:
        names - a set with the names of the fields to be validated
        Returns:
        an object with results of the validation
        Throws:
        FormRuntimeException - if an invalid field name is specified
        IllegalArgumentException - if the set is null
        See Also:
        validateFields()

      • validateForm

        public FormValidatorResults validateForm​(Object model)
        Validates the whole form using the FormValidator. This is an additional validation that can be performed after it was ensured that all fields are syntactically and semantically correct. The aim of this method is to apply high level validation rules that are able to check dependencies between form fields. Calling this method requires that validation of the field level has already been performed (e.g. by validateFields()). If validation is successful (or if no FormValidator is defined), the passed in model object is populated with the content of this form. Otherwise it is not modified.
        Parameters:
        model - the model object; can be null, then no data is copied
        Returns:
        an object with the results of the validation

      • readFields

        public void readFields​(Object bean)
        Reads the form's fields and copies their content into the passed in form bean. Before this method can be called validation of the form's fields must have been successful, i.e. validateFields() must have been invoked and returned a positive result. If validateFields() has not been called before, the passed in bean won't contain the current data of the form's fields. The contents of the fields is converted to the correct data types and written into the bean's properties.
        Parameters:
        bean - the bean in which to store the fields' content; can be null, then this operation has no effect
        Throws:
        FormRuntimeException - if a field cannot be read

      • readFields

        public void readFields​(Object bean,
                       Set<String> names)
        Reads a sub set of this form's fields and writes their content into the specified bean. This method works like the overloaded variant, but operates on a sub set of the fields only. If the passed in set contains an invalid name, a runtime exception is thrown.
        Parameters:
        bean - the bean in which to store the fields' content; can be null, then this operation has no effect
        names - the set with the names of the fields to read
        Throws:
        FormRuntimeException - if a field cannot be read
        IllegalArgumentException - if the set is null