com.vaadin.data.fieldgroup

Class FieldGroup

java.lang.Object

com.vaadin.data.fieldgroup.FieldGroup

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

BeanFieldGroup

public class FieldGroup
extends Object
implements Serializable

FieldGroup provides an easy way of binding fields to data and handling commits of these fields.

The functionality of FieldGroup is similar to Form but FieldGroup does not handle layouts in any way. The typical use case is to create a layout outside the FieldGroup and then use FieldGroup to bind the fields to a data source.

FieldGroup is not a UI component so it cannot be added to a layout. Using the buildAndBind methods FieldGroup can create fields for you using a FieldGroupFieldFactory but you still have to add them to the correct position in your layout.

Since:

7.0

Author:

Vaadin Ltd

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	FieldGroup.BindException
static class	FieldGroup.CommitEvent FIXME javadoc
static class	FieldGroup.CommitException Exception thrown by a FieldGroup when the commit operation fails.
static interface	FieldGroup.CommitHandler CommitHandlers are used by commit() as part of the commit transactions.
static class	FieldGroup.FieldGroupInvalidValueException Exception which wraps InvalidValueExceptions from all invalid fields in a FieldGroup
static class	FieldGroup.SearchException

Constructor Summary

Constructors

Constructor and Description
FieldGroup() Constructs a field binder.
FieldGroup(Item itemDataSource) Constructs a field binder that uses the given data source.

Method Summary

Modifier and Type	Method and Description
void	addCommitHandler(FieldGroup.CommitHandler commitHandler) Adds a commit handler.
void	bind(Field<?> field, Object propertyId) Binds the field with the given propertyId from the current item.
protected void	bindFields() Binds all fields to the properties in the item in use.
void	bindMemberFields(Object objectWithMemberFields) Binds member fields found in the given object.
protected <T extends Field> T	build(String caption, Class<?> dataType, Class<T> fieldType) Creates a field based on the given data type.
Field<?>	buildAndBind(Object propertyId) Builds a field and binds it to the given property id using the field binder.
Field<?>	buildAndBind(String caption, Object propertyId) Builds a field using the given caption and binds it to the given property id using the field binder.
<T extends Field> T	buildAndBind(String caption, Object propertyId, Class<T> fieldType) Builds a field using the given caption and binds it to the given property id using the field binder.
void	buildAndBindMemberFields(Object objectWithMemberFields) Binds member fields found in the given object and builds member fields that have not been initialized.
protected void	buildAndBindMemberFields(Object objectWithMemberFields, boolean buildFields) Binds member fields found in the given object and optionally builds member fields that have not been initialized.
void	clear() Clears the value of all fields.
protected void	clearField(Field<?> field) Clears field and any possible existing binding.
void	commit() Commits all changes done to the bound fields.
protected void	configureField(Field<?> field) Configures a field with the settings set for this FieldBinder.
void	discard() Discards all changes done to the bound fields.
protected Object	findPropertyId(Field memberField) Searches for a property id from the current itemDataSource that matches the given memberField.
Collection<Object>	getBoundPropertyIds() Returns a collection of all property ids that have been bound to fields.
protected Collection<FieldGroup.CommitHandler>	getCommitHandlers() Returns a list of all commit handlers for this FieldGroup.
Field<?>	getField(Object propertyId) Returns the field that is bound to the given property id
FieldGroupFieldFactory	getFieldFactory() Gets the field factory for the FieldGroup.
Collection<Field<?>>	getFields() Returns a collection of all fields that have been bound.
protected static List<Field>	getFieldsInDeclareOrder(Class searchClass) Returns an array containing Field objects reflecting all the fields of the class or interface represented by this Class object.
Item	getItemDataSource() Gets the item used by this FieldBinder.
protected Property	getItemProperty(Object propertyId) Gets the property with the given property id from the item.
Object	getPropertyId(Field<?> field) Returns the property id that is bound to the given field
protected Class<?>	getPropertyType(Object propertyId) Gets the type of the property with the given property id.
Collection<Object>	getUnboundPropertyIds() Returns a collection of all property ids that exist in the item set using setItemDataSource(Item) but have not been bound to fields.
boolean	isBuffered() Checks the buffered mode for the bound fields.
boolean	isEnabled() Returns the enabled status for the fields.
boolean	isModified() Checks if any bound field has been modified.
boolean	isReadOnly() Returns the read only status that is used by default with all fields that have a writable data source.
boolean	isValid() Checks the validity of the bound fields.
protected static String	minifyFieldName(String fieldName)
void	removeCommitHandler(FieldGroup.CommitHandler commitHandler) Removes the given commit handler.
void	setBuffered(boolean buffered) Sets the buffered mode for the bound fields.
void	setEnabled(boolean fieldsEnabled) Updates the enabled state of all bound fields.
void	setFieldFactory(FieldGroupFieldFactory fieldFactory) Sets the field factory for the FieldGroup.
void	setItemDataSource(Item itemDataSource) Updates the item that is used by this FieldBinder.
void	setReadOnly(boolean fieldsReadOnly) Sets the read only state to the given value for all fields with writable data source.
void	unbind(Field<?> field) Detaches the field from its property id and removes it from this FieldBinder.
protected <T> Property.Transactional<T>	wrapInTransactionalProperty(Property<T> itemProperty) Wrap property to transactional property.

Methods inherited from class java.lang.Object

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

Constructor Detail

FieldGroup

public FieldGroup()

Constructs a field binder. Use setItemDataSource(Item) to set a data source for the field binder.

FieldGroup

public FieldGroup(Item itemDataSource)

Constructs a field binder that uses the given data source.

Parameters:

itemDataSource - The data source to bind the fields to

Method Detail

setItemDataSource

public void setItemDataSource(Item itemDataSource)

Updates the item that is used by this FieldBinder. Rebinds all fields to the properties in the new item.

Parameters:

itemDataSource - The new item to use

bindFields

protected void bindFields()

Binds all fields to the properties in the item in use.

Since:

7.7.5

getItemDataSource

public Item getItemDataSource()

Gets the item used by this FieldBinder. Note that you must call commit() for the item to be updated unless buffered mode has been switched off.

Returns:

The item used by this FieldBinder

See Also:

setBuffered(boolean), commit()

isBuffered

public boolean isBuffered()

Checks the buffered mode for the bound fields.

Returns:

true if buffered mode is on, false otherwise

See Also:

for more details on buffered mode, Buffered.isBuffered()

setBuffered

public void setBuffered(boolean buffered)

Sets the buffered mode for the bound fields.

When buffered mode is on the item will not be updated until commit() is called. If buffered mode is off the item will be updated once the fields are updated.

The default is to use buffered mode.

Parameters:

buffered - true to turn on buffered mode, false otherwise

See Also:

Buffered.setBuffered(boolean)

isEnabled

public boolean isEnabled()

Returns the enabled status for the fields.

Note that this will not accurately represent the enabled status of all fields if you change the enabled status of the fields through some other method than setEnabled(boolean).

Returns:

true if the fields are enabled, false otherwise

setEnabled

public void setEnabled(boolean fieldsEnabled)

Updates the enabled state of all bound fields.

Parameters:

fieldsEnabled - true to enable all bound fields, false to disable them

isReadOnly

public boolean isReadOnly()

Returns the read only status that is used by default with all fields that have a writable data source.

Note that this will not accurately represent the read only status of all fields if you change the read only status of the fields through some other method than setReadOnly(boolean).

Returns:

true if the fields are set to read only, false otherwise

setReadOnly

public void setReadOnly(boolean fieldsReadOnly)

Sets the read only state to the given value for all fields with writable data source. Fields with read only data source will always be set to read only.

Parameters:

fieldsReadOnly - true to set the fields with writable data source to read only, false to set them to read write

getFields

public Collection<Field<?>> getFields()

Returns a collection of all fields that have been bound.

The fields are not returned in any specific order.

Returns:

A collection with all bound Fields

bind

public void bind(Field<?> field,
                 Object propertyId)
          throws FieldGroup.BindException

Binds the field with the given propertyId from the current item. If an item has not been set then the binding is postponed until the item is set using setItemDataSource(Item).

This method also adds validators when applicable.

Parameters:

field - The field to bind

propertyId - The propertyId to bind to the field

Throws:

FieldGroup.BindException - If the field is null or the property id is already bound to another field by this field binder

clearField

protected void clearField(Field<?> field)

Clears field and any possible existing binding.

Parameters:

field - The field to be cleared

Since:

7.7.5

wrapInTransactionalProperty

protected <T> Property.Transactional<T> wrapInTransactionalProperty(Property<T> itemProperty)

Wrap property to transactional property.

getItemProperty

protected Property getItemProperty(Object propertyId)
                            throws FieldGroup.BindException

Gets the property with the given property id from the item.

Parameters:

propertyId - The id if the property to find

Returns:

The property with the given id from the item

Throws:

FieldGroup.BindException - If the property was not found in the item or no item has been set

unbind

public void unbind(Field<?> field)
            throws FieldGroup.BindException

Detaches the field from its property id and removes it from this FieldBinder.

Note that the field is not detached from its property data source if it is no longer connected to the same property id it was bound to using this FieldBinder.

Parameters:

field - The field to detach

Throws:

FieldGroup.BindException - If the field is not bound by this field binder or not bound to the correct property id

configureField

protected void configureField(Field<?> field)

Configures a field with the settings set for this FieldBinder.

By default this updates the buffered, read only and enabled state of the field. Also adds validators when applicable. Fields with read only data source are always configured as read only.

Parameters:

field - The field to update

getPropertyType

protected Class<?> getPropertyType(Object propertyId)
                            throws FieldGroup.BindException

Gets the type of the property with the given property id.

Parameters:

propertyId - The propertyId. Must be find

Returns:

The type of the property

Throws:

FieldGroup.BindException

getBoundPropertyIds

public Collection<Object> getBoundPropertyIds()

Returns a collection of all property ids that have been bound to fields.

Note that this will return property ids even before the item has been set. In that case it returns the property ids that will be bound once the item is set.

No guarantee is given for the order of the property ids

Returns:

A collection of bound property ids

getUnboundPropertyIds

public Collection<Object> getUnboundPropertyIds()

Returns a collection of all property ids that exist in the item set using setItemDataSource(Item) but have not been bound to fields.

Will always return an empty collection before an item has been set using setItemDataSource(Item).

No guarantee is given for the order of the property ids

Returns:

A collection of property ids that have not been bound to fields

commit

public void commit()
            throws FieldGroup.CommitException

Commits all changes done to the bound fields.

Calls all FieldGroup.CommitHandlers before and after committing the field changes to the item data source. The whole commit is aborted and state is restored to what it was before commit was called if any FieldGroup.CommitHandler throws a CommitException or there is a problem committing the fields

Throws:

FieldGroup.CommitException - If the commit was aborted

discard

public void discard()

Discards all changes done to the bound fields.

Only has effect if buffered mode is used.

getField

public Field<?> getField(Object propertyId)

Returns the field that is bound to the given property id

Parameters:

propertyId - The property id to use to lookup the field

Returns:

The field that is bound to the property id or null if no field is bound to that property id

getPropertyId

public Object getPropertyId(Field<?> field)

Returns the property id that is bound to the given field

Parameters:

field - The field to use to lookup the property id

Returns:

The property id that is bound to the field or null if the field is not bound to any property id by this FieldBinder

addCommitHandler

public void addCommitHandler(FieldGroup.CommitHandler commitHandler)

Adds a commit handler.

The commit handler is called before the field values are committed to the item ( CommitHandler#preCommit(CommitEvent)) and after the item has been updated (CommitHandler#postCommit(CommitEvent)). If a FieldGroup.CommitHandler throws a CommitException the whole commit is aborted and the fields retain their old values.

Parameters:

commitHandler - The commit handler to add

removeCommitHandler

public void removeCommitHandler(FieldGroup.CommitHandler commitHandler)

Removes the given commit handler.

Parameters:

commitHandler - The commit handler to remove

See Also:

addCommitHandler(CommitHandler)

getCommitHandlers

protected Collection<FieldGroup.CommitHandler> getCommitHandlers()

Returns a list of all commit handlers for this FieldGroup.

Use addCommitHandler(CommitHandler) and removeCommitHandler(CommitHandler) to register or unregister a commit handler.

Returns:

A collection of commit handlers

isValid

public boolean isValid()

Checks the validity of the bound fields.

Call the Validatable.validate() for the fields to get the individual error messages.

Returns:

true if all bound fields are valid, false otherwise.

isModified

public boolean isModified()

Checks if any bound field has been modified.

Returns:

true if at least one field has been modified, false otherwise

getFieldFactory

public FieldGroupFieldFactory getFieldFactory()

Gets the field factory for the FieldGroup. The field factory is only used when FieldGroup creates a new field.

Returns:

The field factory in use

setFieldFactory

public void setFieldFactory(FieldGroupFieldFactory fieldFactory)

Sets the field factory for the FieldGroup. The field factory is only used when FieldGroup creates a new field.

Parameters:

fieldFactory - The field factory to use

bindMemberFields

public void bindMemberFields(Object objectWithMemberFields)
                      throws FieldGroup.BindException

Binds member fields found in the given object.

This method processes all (Java) member fields whose type extends Field and that can be mapped to a property id. Property id mapping is done based on the field name or on a @PropertyId annotation on the field. All non-null fields for which a property id can be determined are bound to the property id.

For example:

 public class MyForm extends VerticalLayout {
 private TextField firstName = new TextField("First name");
 @PropertyId("last")
 private TextField lastName = new TextField("Last name");
 private TextField age = new TextField("Age"); ... }

 MyForm myForm = new MyForm();
 ...
 fieldGroup.bindMemberFields(myForm);
 

This binds the firstName TextField to a "firstName" property in the item, lastName TextField to a "last" property and the age TextField to a "age" property.

Parameters:

objectWithMemberFields - The object that contains (Java) member fields to bind

Throws:

FieldGroup.BindException - If there is a problem binding a field

buildAndBindMemberFields

public void buildAndBindMemberFields(Object objectWithMemberFields)
                              throws FieldGroup.BindException

Binds member fields found in the given object and builds member fields that have not been initialized.

This method processes all (Java) member fields whose type extends Field and that can be mapped to a property id. Property ids are searched in the following order: @PropertyId annotations, exact field name matches and the case-insensitive matching that ignores underscores. Fields that are not initialized (null) are built using the field factory. All non-null fields for which a property id can be determined are bound to the property id.

For example:

 public class MyForm extends VerticalLayout {
 private TextField firstName = new TextField("First name");
 @PropertyId("last")
 private TextField lastName = new TextField("Last name");
 private TextField age;

 MyForm myForm = new MyForm();
 ...
 fieldGroup.buildAndBindMemberFields(myForm);
 

This binds the firstName TextField to a "firstName" property in the item, lastName TextField to a "last" property and builds an age TextField using the field factory and then binds it to the "age" property.

Parameters:

objectWithMemberFields - The object that contains (Java) member fields to build and bind

Throws:

FieldGroup.BindException - If there is a problem binding or building a field

buildAndBindMemberFields

protected void buildAndBindMemberFields(Object objectWithMemberFields,
                                        boolean buildFields)
                                 throws FieldGroup.BindException

Binds member fields found in the given object and optionally builds member fields that have not been initialized.

This method processes all (Java) member fields whose type extends Field and that can be mapped to a property id. Property ids are searched in the following order: @PropertyId annotations, exact field name matches and the case-insensitive matching that ignores underscores. Fields that are not initialized (null) are built using the field factory is buildFields is true. All non-null fields for which a property id can be determined are bound to the property id.

Parameters:

objectWithMemberFields - The object that contains (Java) member fields to build and bind

Throws:

FieldGroup.BindException - If there is a problem binding or building a field

findPropertyId

protected Object findPropertyId(Field memberField)

Searches for a property id from the current itemDataSource that matches the given memberField.

If perfect match is not found, uses a case insensitive search that also ignores underscores. Returns null if no match is found. Throws a SearchException if no item data source has been set.

The propertyId search logic used by buildAndBindMemberFields can easily be customized by overriding this method. No other changes are needed.

Parameters:

memberField - The field an object id is searched for

Returns:

minifyFieldName

protected static String minifyFieldName(String fieldName)

buildAndBind

public Field<?> buildAndBind(Object propertyId)
                      throws FieldGroup.BindException

Builds a field and binds it to the given property id using the field binder.

Parameters:

propertyId - The property id to bind to. Must be present in the field finder.

Returns:

The created and bound field

Throws:

FieldGroup.BindException - If there is a problem while building or binding

buildAndBind

public Field<?> buildAndBind(String caption,
                             Object propertyId)
                      throws FieldGroup.BindException

Builds a field using the given caption and binds it to the given property id using the field binder.

Parameters:

caption - The caption for the field

propertyId - The property id to bind to. Must be present in the field finder.

Returns:

The created and bound field. Can be any type of Field.

Throws:

FieldGroup.BindException - If there is a problem while building or binding

buildAndBind

public <T extends Field> T buildAndBind(String caption,
                                        Object propertyId,
                                        Class<T> fieldType)
                                 throws FieldGroup.BindException

Builds a field using the given caption and binds it to the given property id using the field binder. Ensures the new field is of the given type.

Parameters:

caption - The caption for the field

propertyId - The property id to bind to. Must be present in the field finder.

Returns:

The created and bound field. Can be any type of Field.

Throws:

FieldGroup.BindException - If the field could not be created

build

protected <T extends Field> T build(String caption,
                                    Class<?> dataType,
                                    Class<T> fieldType)
                             throws FieldGroup.BindException

Creates a field based on the given data type.

The data type is the type that we want to edit using the field. The field type is the type of field we want to create, can be Field if any Field is good.

Parameters:

caption - The caption for the new field

dataType - The data model type that we want to edit using the field

fieldType - The type of field that we want to create

Returns:

A Field capable of editing the given type

Throws:

FieldGroup.BindException - If the field could not be created

getFieldsInDeclareOrder

protected static List<Field> getFieldsInDeclareOrder(Class searchClass)

Returns an array containing Field objects reflecting all the fields of the class or interface represented by this Class object. The elements in the array returned are sorted in declare order from sub class to super class.

Parameters:

searchClass -

Returns:

clear

public void clear()

Clears the value of all fields.

Since:

7.4