Package com.vaadin.data.fieldgroup

Class 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

    • 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()

      • 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

      • 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

      • 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

      • 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