Package org.dellroad.stuff.vaadin7

Class FieldBuilder

java.lang.Object

org.dellroad.stuff.vaadin7.FieldBuilder

public class FieldBuilder
extends Object

Automatically builds and binds fields for a Java bean annotated with FieldBuilder annotations. The various nested FieldBuilder annotation types annotate Java bean property "getter" methods and specify how the the bean properties of that class should be edited using FieldBuilder.AbstractFields. This allows all information about how to edit a Java model class to stay contained within that class.

This class supports two types of annotations: first, the @ProvidesField annotation annotates a method that knows how to build an FieldBuilder.AbstractField suitable for editing the bean property specified by its value(). So @ProvidesField is analgous to @ProvidesProperty, except that it defines an editing field rather than a container property.

The @FieldBuilder.AbstractField hierarchy annotations are the other type of annotation. These annotations annotate a Java bean property getter method and specify how to configure an FieldBuilder.AbstractField subclass instance to edit the bean property corresponding to the getter method. @FieldBuilder.AbstractField is the top level annotation in a hierarchy of annotations that correspond to the FieldBuilder.AbstractField class hierarchy. @FieldBuilder.AbstractField corresponds to FieldBuilder.AbstractField, and its properties configure corresponding FieldBuilder.AbstractField properties. More specific annotations correspond to the various FieldBuilder.AbstractField subclasses, for example @FieldBuilder.ComboBox corresponds to FieldBuilder.ComboBox. When using more specific annotations, the "superclass" annotations configure the corresponding superclass' properties.

A simple example shows how these annotations are used:

 // Use a 10x40 TextArea to edit the "description" property
 @FieldBuilder.AbstractField(caption = "Description:")
 @FieldBuilder.TextArea(columns = 40, rows = 10)
 public String getDescription() {
     return this.description;
 }

 // Use my own custom field to edit the "foobar" property
 @FieldBuilder.ProvidesField("foobar")
 private MyCustomField createFoobarField() {
     ...
 }
 

A FieldBuilder instance will read these annotations and build the fields automatically. For example:

 // Create fields based on FieldGroup.* annotations
 Person person = new Person("Joe Smith", 100);
 BeanFieldGroup<Person> fieldGroup = FieldBuilder.buildFieldGroup(person);

 // Layout the fields in a form
 FormLayout layout = new FormLayout();
 for (Field<?> field : fieldGroup.getFields())
     layout.addComponent(field);
 

For all annotations in the @FieldBuilder.AbstractField hierarchy, leaving properties set to their default values results in the default behavior.

See Also:

FieldBuilder.AbstractSelect, FieldBuilder.AbstractTextField, FieldBuilder.CheckBox, FieldBuilder.ComboBox, FieldBuilder.DateField, FieldBuilder.EnumComboBox, FieldBuilder.ListSelect, FieldBuilder.PasswordField, FieldBuilder.TextArea, FieldBuilder.TextField

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	FieldBuilder.AbstractField	Specifies how a Java property should be edited in Vaadin using an AbstractField.
static interface	FieldBuilder.AbstractSelect	Specifies how a Java property should be edited in Vaadin using an AbstractSelect.
static interface	FieldBuilder.AbstractTextField	Specifies how a Java property should be edited in Vaadin using a AbstractTextField.
protected static class	FieldBuilder.AnnotationApplier<A extends Annotation,F extends AbstractField<?>>	Class that knows how to apply annotation properties to a corresponding field.
static interface	FieldBuilder.CheckBox	Specifies how a Java property should be edited in Vaadin using an CheckBox.
static interface	FieldBuilder.ComboBox	Specifies how a Java property should be edited in Vaadin using an ComboBox.
static interface	FieldBuilder.DateField	Specifies how a Java property should be edited in Vaadin using an DateField.
static interface	FieldBuilder.EnumComboBox	Specifies how a Java property should be edited in Vaadin using an EnumComboBox.
static interface	FieldBuilder.ListSelect	Specifies how a Java property should be edited in Vaadin using an ListSelect.
static interface	FieldBuilder.PasswordField	Specifies how a Java property should be edited in Vaadin using a PasswordField.
static interface	FieldBuilder.ProvidesField	Specifies that the annotated method will return an AbstractField suitable for editing the specified property.
static interface	FieldBuilder.TextArea	Specifies how a Java property should be edited in Vaadin using a TextArea.
static interface	FieldBuilder.TextField	Specifies how a Java property should be edited in Vaadin using a TextField.

Constructor Summary

Constructors

Constructor	Description
FieldBuilder()

Method Summary

Modifier and Type	Method	Description
void	buildAndBind(BeanFieldGroup<?> fieldGroup)	Introspect for FieldBuilder annotations on property getter methods of the BeanFieldGroup's data source, and then build and bind the corresponding fields.
protected List<FieldBuilder.AnnotationApplier<?,?>>	buildApplierList(Method method)	Find all relevant annotations on the given method as well as on any supertype methods it overrides.
Map<String,Field<?>>	buildBeanPropertyFields(Object bean)	Introspect for FieldBuilder annotations on property getter methods and build a mapping from Java bean property name to a field that may be used to edit that property.
protected List<FieldBuilder.AnnotationApplier<?,?>>	buildDirectApplierList(Method method)	Find all relevant annotations declared directly on the given Method.
protected AbstractField<?>	buildField(Collection<FieldBuilder.AnnotationApplier<?,?>> appliers, String description)	Instantiate and configure an FieldBuilder.AbstractField according to the given scanned annotations.
static <T> BeanFieldGroup<T>	buildFieldGroup(T bean)	Create a BeanFieldGroup using the given instance, introspect for FieldBuilder annotations on property getter methods of the given bean's class, and build and bind the corresponding fields, and return the result.
protected FieldBuilder.AnnotationApplier<?,?>	getAnnotationApplier(Method method, Annotation annotation)	Get the FieldBuilder.AnnotationApplier that applies the given annotation.

Methods inherited from class java.lang.Object

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

Constructor Detail

FieldBuilder

public FieldBuilder()

Method Detail

buildAndBind

public void buildAndBind(BeanFieldGroup<?> fieldGroup)

Introspect for FieldBuilder annotations on property getter methods of the BeanFieldGroup's data source, and then build and bind the corresponding fields.

Parameters:

fieldGroup - field group to configure

Throws:

IllegalArgumentException - if fieldGroup is null

IllegalArgumentException - if fieldGroup does not yet have a data source

buildBeanPropertyFields

public Map<String,Field<?>> buildBeanPropertyFields(Object bean)

Introspect for FieldBuilder annotations on property getter methods and build a mapping from Java bean property name to a field that may be used to edit that property. Only bean properties that have FieldBuilder annotations are detected.

Parameters:

bean - Java bean

Returns:

mapping from bean property name to field

Throws:

IllegalArgumentException - if bean is null

IllegalArgumentException - if invalid or conflicting annotations are encountered

buildFieldGroup

public static <T> BeanFieldGroup<T> buildFieldGroup(T bean)

Create a BeanFieldGroup using the given instance, introspect for FieldBuilder annotations on property getter methods of the given bean's class, and build and bind the corresponding fields, and return the result.

Type Parameters:

T - bean type

Parameters:

bean - model bean annotated with FieldBuilder annotations

Returns:

new BeanFieldGroup

Throws:

IllegalArgumentException - if bean is null

buildField

protected AbstractField<?> buildField(Collection<FieldBuilder.AnnotationApplier<?,?>> appliers,
                                      String description)

Instantiate and configure an FieldBuilder.AbstractField according to the given scanned annotations.

Parameters:

appliers - annotation appliers

description - description of the field (used for exception messages)

Returns:

new field

buildApplierList

protected List<FieldBuilder.AnnotationApplier<?,?>> buildApplierList(Method method)

Find all relevant annotations on the given method as well as on any supertype methods it overrides. The method must be a getter method taking no arguments. Annotations are ordered so that annotations on a method in type X appear before annotations on an overridden method in type Y, a supertype of X.

Parameters:

method - annotated getter method

Returns:

appliers for annotations found

Throws:

IllegalArgumentException - if method is null

IllegalArgumentException - if method has parameters

buildDirectApplierList

protected List<FieldBuilder.AnnotationApplier<?,?>> buildDirectApplierList(Method method)

Find all relevant annotations declared directly on the given Method.

Parameters:

method - method to inspect

Returns:

annotations found

Throws:

IllegalArgumentException - if method is null

getAnnotationApplier

protected FieldBuilder.AnnotationApplier<?,?> getAnnotationApplier(Method method,
                                                                         Annotation annotation)

Get the FieldBuilder.AnnotationApplier that applies the given annotation. Subclasses can add support for additional annotation types by overriding this method.

Parameters:

method - method to inspect

annotation - method annotation to inspect

Returns:

corresponding FieldBuilder.AnnotationApplier, or null if annotation is unknown