Form (JGUIraffe BOM 1.3.1 API)

java.lang.Object
- net.sf.jguiraffe.gui.forms.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 Summary

Constructors
Constructor and Description

Form(TransformerContext ctx, BindingStrategy strat)
Creates a new instance of Form and initializes it with all required helper objects.

Constructors
Constructor and Description
`Form(TransformerContext ctx, BindingStrategy strat)` Creates a new instance of `Form` and initializes it with all required helper objects.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addField(String name, FieldHandler fld)` Adds the specified field to this form.
`BindingStrategy`	`getBindingStrategy()` Returns the `BindingStrategy` used by this form.
`ComponentStore`	`getComponentStore()` Returns the component store of this form.
`String`	`getDisplayName(String fldName)` Returns the display name for the specified field.
`FieldHandler`	`getField(String name)` Returns the `FieldHandler` object for the field with the given name.
`Set<String>`	`getFieldNames()` Returns a set with the names of all defined fields.
`FormValidator`	`getFormValidator()` Returns the form validator.
`TransformerContext`	`getTransformerContext()` Returns the transformer context.
`void`	`initFields(Object bean)` Fills the form's fields with the properties of the passed in bean.
`void`	`initFields(Object bean, Set<String> names)` Fills a sub set of the form's fields with the properties of the passed in bean.
`void`	`readFields(Object bean)` Reads the form's fields and copies their content into the passed in form bean.
`void`	`readFields(Object bean, Set<String> names)` Reads a sub set of this form's fields and writes their content into the specified bean.
`void`	`setFormValidator(FormValidator formValidator)` Sets the form validator.
`FormValidatorResults`	`validate(Object model)` Validates this form and writes its content into the specified model object if validation is successful.
`FormValidatorResults`	`validateFields()` Validates the fields of this form.
`FormValidatorResults`	`validateFields(Set<String> names)` Validates a sub set of the fields of this form.
`FormValidatorResults`	`validateForm(Object model)` Validates the whole form using the `FormValidator`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- 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

Class Form

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Form

Method Detail

getTransformerContext

getBindingStrategy

getFormValidator

setFormValidator

addField

initFields

initFields

validate

getFieldNames

getField

getDisplayName

getComponentStore

validateFields

validateFields

validateForm

readFields

readFields