com.vaadin.flow.data.binder.
Class Binder<BEAN>
- java.lang.Object
-
- com.vaadin.flow.data.binder.Binder<BEAN>
-
Type Parameters:
BEAN
- the bean typeAll Implemented Interfaces:
Direct Known Subclasses:
public class Binder<BEAN> extends Object implements Serializable
Connects one or more
Field
components to properties of a backing data type such as a bean type. With a binder, input components can be grouped together into forms to easily create and update business objects with little explicit logic needed to move data between the UI and the data layers of the application.A binder is a collection of bindings, each representing the mapping of a single field, through converters and validators, to a backing property.
A binder instance can be bound to a single bean instance at a time, but can be rebound as needed. This allows usage patterns like a master-details view, where a select component is used to pick the bean to edit.
Bean level validators can be added using the
withValidator(Validator)
method and will be run on the bound bean once it has been updated from the values of the bound fields. Bean level validators are also run as part ofwriteBean(Object)
andwriteBeanIfValid(Object)
if all field level validators pass.Note: For bean level validators, the bean must be updated before the validators are run. If a bean level validator fails in
writeBean(Object)
orwriteBeanIfValid(Object)
, the bean will be reverted to the previous state before returning from the method. You should ensure that the getters/setters in the bean do not have side effects.Unless otherwise specified,
Binder
method arguments cannot be null.Since:
1.0.
Author:
Vaadin Ltd
See Also:
Binder.BindingBuilder
,Binder.Binding
,HasValue
, Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class and Description static interface
Binder.Binding<BEAN,TARGET>
Represents the binding between a field and a data property.
static interface
Binder.BindingBuilder<BEAN,TARGET>
Creates a binding between a field and a data property.
protected static class
Binder.BindingBuilderImpl<BEAN,FIELDVALUE,TARGET>
An internal implementation of
BindingBuilder
.protected static class
Binder.BindingImpl<BEAN,FIELDVALUE,TARGET>
An internal implementation of
Binding
.
-
Constructor Summary
Constructors Modifier Constructor and Description Binder()
Creates a new binder without support for creating bindings based on property names.
Binder(Class<BEAN> beanType)
Creates a new binder that uses reflection based on the provided bean type to resolve bean properties.
Binder(Class<BEAN> beanType, boolean scanNestedDefinitions)
Creates a new binder that uses reflection based on the provided bean type to resolve bean properties.
protected
Binder(PropertySet<BEAN> propertySet)
Creates a binder using a custom
PropertySet
implementation for finding and resolving property names forbindInstanceFields(Object)
,bind(HasValue, String)
andBinder.BindingBuilder.bind(String)
.
-
Method Summary
All Methods Modifier and Type Method and Description protected <T> Registration
addListener(Class<T> eventType, SerializableConsumer<T> method)
Adds a listener to the binder.
Registration
addStatusChangeListener(StatusChangeListener listener)
Adds status change listener to the binder.
Registration
addValueChangeListener(HasValue.ValueChangeListener<? super HasValue.ValueChangeEvent<?>> listener)
Adds field value change listener to all the fields in the binder.
<FIELDVALUE>
Binder.Binding<BEAN,FIELDVALUE>bind(HasValue<?,FIELDVALUE> field, String propertyName)
Binds the given field to the property with the given name.
<FIELDVALUE>
Binder.Binding<BEAN,FIELDVALUE>bind(HasValue<?,FIELDVALUE> field, ValueProvider<BEAN,FIELDVALUE> getter, Setter<BEAN,FIELDVALUE> setter)
Binds a field to a bean property represented by the given getter and setter pair.
void
bindInstanceFields(Object objectWithMemberFields)
Binds member fields found in the given object.
protected void
clearError(HasValue<?,?> field)
Clears the error condition of the given field, if any.
protected Binder.BindingBuilder<BEAN,?>
configureBinding(Binder.BindingBuilder<BEAN,?> binding, PropertyDefinition<BEAN,?> definition)
Configures the
binding
with the property definitiondefinition
before it's being bound.protected <FIELDVALUE,TARGET>
Binder.BindingBuilder<BEAN,TARGET>createBinding(HasValue<?,FIELDVALUE> field, Converter<FIELDVALUE,TARGET> converter, BindingValidationStatusHandler handler)
Creates a new binding with the given field.
protected <FIELDVALUE,TARGET>
Binder.BindingBuilder<BEAN,TARGET>doCreateBinding(HasValue<?,FIELDVALUE> field, Converter<FIELDVALUE,TARGET> converter, BindingValidationStatusHandler handler)
<FIELDVALUE>
Binder.BindingBuilder<BEAN,FIELDVALUE>forField(HasValue<?,FIELDVALUE> field)
Creates a new binding for the given field.
<FIELDVALUE>
Binder.BindingBuilder<BEAN,FIELDVALUE>forMemberField(HasValue<?,FIELDVALUE> field)
Creates a new binding for the given field.
BEAN
getBean()
Returns the bean that has been bound with
bind(com.vaadin.flow.component.HasValue<?, FIELDVALUE>, com.vaadin.flow.function.ValueProvider<BEAN, FIELDVALUE>, com.vaadin.flow.data.binder.Setter<BEAN, FIELDVALUE>)
, or null if a bean is not currently bound.protected Map<Binder.Binding<BEAN,?>,Object>
getBeanState(BEAN bean, Collection<Binder.Binding<BEAN,?>> bindings)
Stores the state of the given bean.
Optional<Binder.Binding<BEAN,?>>
getBinding(String propertyName)
Gets the binding for a property name.
protected Collection<Binder.BindingImpl<BEAN,?,?>>
getBindings()
Returns the bindings for this binder.
Stream<HasValue<?,?>>
getFields()
Returns the fields this binder has been bound to.
Optional<HasText>
getStatusLabel()
Gets the status label or an empty optional if none has been set.
BinderValidationStatusHandler<BEAN>
getValidationStatusHandler()
Gets the status handler of this form.
protected void
handleBinderValidationStatus(BinderValidationStatus<BEAN> binderStatus)
The default binder level status handler.
protected void
handleError(HasValue<?,?> field, ValidationResult result)
Handles a validation error emitted when trying to write the value of the given field.
protected void
handleFieldValueChange(Binder.Binding<BEAN,?> binding)
Informs the Binder that a value in Binding was changed.
protected void
handleValidationStatus(BindingValidationStatus<?> status)
Default
BindingValidationStatusHandler
functional method implementation.boolean
hasChanges()
Check whether any of the bound fields' have uncommitted changes since last explicit call to
readBean(Object)
,removeBean()
,writeBean(Object)
orwriteBeanIfValid(Object)
.boolean
isValid()
Runs all currently configured field level validators, as well as all bean level validators if a bean is currently set with
setBean(Object)
, and returns whether any of the validators failed.boolean
isValidatorsDisabled()
Returns if the validators including bean level validators are disabled or enabled for this Binder.
void
readBean(BEAN bean)
Reads the bound property values from the given bean to the corresponding fields.
void
removeBean()
Removes the currently set bean and clears bound fields.
void
removeBinding(Binder.Binding<BEAN,?> binding)
Removes the given Binding from this Binder.
void
removeBinding(HasValue<?,?> field)
Finds and removes all Bindings for the given field.
void
removeBinding(String propertyName)
Finds and removes the Binding for the given property name.
protected void
removeBindingInternal(Binder.Binding<BEAN,?> binding)
Removes (internally) the
Binding
from the bound properties map (if present) and from the list ofBinding
s.protected void
restoreBeanState(BEAN bean, Map<Binder.Binding<BEAN,?>,Object> oldValues)
Restores the state of the bean from the given values.
void
setBean(BEAN bean)
Binds the given bean to all the fields added to this Binder.
void
setReadOnly(boolean readOnly)
Sets the read only state to the given value for all currently bound fields.
void
setStatusLabel(HasText statusLabel)
Sets the label to show the binder level validation errors not related to any specific field.
void
setValidationStatusHandler(BinderValidationStatusHandler<BEAN> statusHandler)
Sets the status handler to track form status changes.
void
setValidatorsDisabled(boolean validatorsDisabled)
Control whether validators including bean level validators are disabled or enabled globally for this Binder.
BinderValidationStatus<BEAN>
validate()
Validates the values of all bound fields and returns the validation status.
protected BinderValidationStatus<BEAN>
validate(boolean fireEvent)
Validates the values of all bound fields and returns the validation status.
static <BEAN> Binder<BEAN>
withPropertySet(PropertySet<BEAN> propertySet)
Creates a binder using a custom
PropertySet
implementation for finding and resolving property names forbindInstanceFields(Object)
,bind(HasValue, String)
andBinder.BindingBuilder.bind(String)
.Binder<BEAN>
withValidator(SerializablePredicate<BEAN> predicate, ErrorMessageProvider errorMessageProvider)
A convenience method to add a validator to this binder using the
Validator.from(SerializablePredicate, ErrorMessageProvider)
factory method.Binder<BEAN>
withValidator(SerializablePredicate<BEAN> predicate, String message)
A convenience method to add a validator to this binder using the
Validator.from(SerializablePredicate, String)
factory method.Binder<BEAN>
withValidator(Validator<? super BEAN> validator)
Adds an bean level validator.
void
writeBean(BEAN bean)
Writes changes from the bound fields to the given bean if all validators (binding and bean level) pass.
void
writeBeanAsDraft(BEAN bean)
Writes successfully converted and validated changes from the bound fields to the bean even if there are other fields with non-validated changes.
void
writeBeanAsDraft(BEAN bean, boolean forced)
Writes successfully converted changes from the bound fields bypassing all the Validation or all fields passing conversion if forced = true.
boolean
writeBeanIfValid(BEAN bean)
Writes changes from the bound fields to the given bean if all validators (binding and bean level) pass.
-
-
-
Constructor Detail
-
Binder
protected Binder(PropertySet<BEAN> propertySet)
Creates a binder using a custom
PropertySet
implementation for finding and resolving property names forbindInstanceFields(Object)
,bind(HasValue, String)
andBinder.BindingBuilder.bind(String)
.Parameters:
propertySet
- the property set implementation to use, notnull
.
-
Binder
public Binder(Class<BEAN> beanType)
Creates a new binder that uses reflection based on the provided bean type to resolve bean properties.
Parameters:
beanType
- the bean type to use, notnull
-
Binder
public Binder()
Creates a new binder without support for creating bindings based on property names. Use an alternative constructor, such as
Binder(Class)
, to create a binder that support creating bindings based on instance fields throughbindInstanceFields(Object)
, or based on a property name throughbind(HasValue, String)
orBinder.BindingBuilder.bind(String)
.
-
Binder
public Binder(Class<BEAN> beanType, boolean scanNestedDefinitions)
Creates a new binder that uses reflection based on the provided bean type to resolve bean properties.
Parameters:
beanType
- the bean type to use, notnull
scanNestedDefinitions
- iftrue
, scan for nested property definitions as well
-
-
Method Detail
-
withPropertySet
public static <BEAN> Binder<BEAN> withPropertySet(PropertySet<BEAN> propertySet)
Creates a binder using a custom
PropertySet
implementation for finding and resolving property names forbindInstanceFields(Object)
,bind(HasValue, String)
andBinder.BindingBuilder.bind(String)
.This functionality is provided as static method instead of as a public constructor in order to make it possible to use a custom property set without creating a subclass while still leaving the public constructors focused on the common use cases.
Type Parameters:
BEAN
- the bean typeParameters:
propertySet
- the property set implementation to use, notnull
.Returns:
a new binder using the provided property set, not
null
See Also:
-
handleFieldValueChange
protected void handleFieldValueChange(Binder.Binding<BEAN,?> binding)
Informs the Binder that a value in Binding was changed. This method will trigger validating and writing of the whole bean if using
setBean(Object)
. If usingreadBean(Object)
only the field validation is run.Parameters:
binding
- the binding whose value has been changed
-
getBean
public BEAN getBean()
Returns the bean that has been bound with
bind(com.vaadin.flow.component.HasValue<?, FIELDVALUE>, com.vaadin.flow.function.ValueProvider<BEAN, FIELDVALUE>, com.vaadin.flow.data.binder.Setter<BEAN, FIELDVALUE>)
, or null if a bean is not currently bound.Returns:
the currently bound bean if any
-
forField
public <FIELDVALUE> Binder.BindingBuilder<BEAN,FIELDVALUE> forField(HasValue<?,FIELDVALUE> field)
Creates a new binding for the given field. The returned builder may be further configured before invoking
Binder.BindingBuilder.bind(ValueProvider, Setter)
which completes the binding. UntilBinding.bind
is called, the binding has no effect.Note: Not all
HasValue
implementations support passingnull
as the value. For these the Binder will automatically changenull
to a null representation provided byHasValue.getEmptyValue()
. This conversion is one-way only, if you want to have a two-way mapping back tonull
, useBinder.BindingBuilder.withNullRepresentation(Object)
.Type Parameters:
FIELDVALUE
- the value type of the fieldParameters:
field
- the field to be bound, not nullReturns:
the new binding
See Also:
-
forMemberField
public <FIELDVALUE> Binder.BindingBuilder<BEAN,FIELDVALUE> forMemberField(HasValue<?,FIELDVALUE> field)
Creates a new binding for the given field. The returned builder may be further configured before invoking
bindInstanceFields(Object)
. Unlike with theforField(HasValue)
method, no explicit call toBinder.BindingBuilder.bind(String)
is needed to complete this binding in the case that the name of the field matches a field name found in the bean.Type Parameters:
FIELDVALUE
- the value type of the fieldParameters:
field
- the field to be bound, not nullReturns:
the new binding builder
See Also:
-
bind
public <FIELDVALUE> Binder.Binding<BEAN,FIELDVALUE> bind(HasValue<?,FIELDVALUE> field, ValueProvider<BEAN,FIELDVALUE> getter, Setter<BEAN,FIELDVALUE> setter)
Binds a field to a bean property represented by the given getter and setter pair. The functions are used to update the field value from the property and to store the field value to the property, respectively.
Use the
forField(HasValue)
overload instead if you want to further configure the new binding.Note: Not all
HasValue
implementations support passingnull
as the value. For these the Binder will automatically changenull
to a null representation provided byHasValue.getEmptyValue()
. This conversion is one-way only, if you want to have a two-way mapping back tonull
, useforField(HasValue)
andBinder.BindingBuilder.withNullRepresentation(Object)
.When a bean is bound with
setBean(Object)
, the field value is set to the return value of the given getter. The property value is then updated via the given setter whenever the field value changes. The setter may be null; in that case the property value is never updated and the binding is said to be read-only.If the Binder is already bound to some bean, the newly bound field is associated with the corresponding bean property as described above.
The getter and setter can be arbitrary functions, for instance implementing user-defined conversion or validation. However, in the most basic use case you can simply pass a pair of method references to this method as follows:
class Person { public String getName() { ... } public void setName(String name) { ... } } TextField nameField = new TextField(); binder.bind(nameField, Person::getName, Person::setName);
Note: when a
null
setter is given the field will be marked as read-only by invoking (HasValue.setReadOnly(boolean)
.Type Parameters:
FIELDVALUE
- the value type of the fieldParameters:
field
- the field to bind, not nullgetter
- the function to get the value of the property to the field, not nullsetter
- the function to write the field value to the property or null if read-onlyReturns:
the newly created binding
-
bind
public <FIELDVALUE> Binder.Binding<BEAN,FIELDVALUE> bind(HasValue<?,FIELDVALUE> field, String propertyName)
Binds the given field to the property with the given name. The getter and setter of the property are looked up using a
PropertySet
.For a
Binder
created using theBinder(Class)
constructor, introspection will be used to find a Java Bean property. If a JSR-303 bean validation implementation is present on the classpath, aBeanValidator
is also added to the binding.The property must have an accessible getter method. It need not have an accessible setter; in that case the property value is never updated and the binding is said to be read-only.
Type Parameters:
FIELDVALUE
- the value type of the field to bindParameters:
field
- the field to bind, not nullpropertyName
- the name of the property to bind, not nullReturns:
the newly created binding
Throws:
IllegalArgumentException
- if the property name is invalidIllegalArgumentException
- if the property has no accessible getterIllegalStateException
- if the binder is not configured with an appropriatePropertySet
See Also:
-
setBean
public void setBean(BEAN bean)
Binds the given bean to all the fields added to this Binder. A
null
value removes a currently bound bean.When a bean is bound, the field values are updated by invoking their corresponding getter functions. Any changes to field values are reflected back to their corresponding property values of the bean as long as the bean is bound.
Any change made in the fields also runs validation for the field
Binder.Binding
and bean level validation for this binder (bean level validators are added usingwithValidator(Validator)
.After updating each field, the value is read back from the field and the bean's property value is updated if it has been changed from the original value by the field or a converter.
Parameters:
bean
- the bean to edit, ornull
to remove a currently bound bean and clear bound fieldsSee Also:
readBean(Object)
,writeBean(Object)
,writeBeanIfValid(Object)
-
removeBean
public void removeBean()
Removes the currently set bean and clears bound fields. If there is no bound bean, does nothing.
This is a shorthand for
setBean(Object)
withnull
bean.
-
readBean
public void readBean(BEAN bean)
Reads the bound property values from the given bean to the corresponding fields.
The bean is not otherwise associated with this binder; in particular its property values are not bound to the field value changes. To achieve that, use
setBean(Object)
.Parameters:
bean
- the bean whose property values to read ornull
to clear bound fieldsSee Also:
setBean(Object)
,writeBeanIfValid(Object)
,writeBean(Object)
-
writeBean
public void writeBean(BEAN bean) throws ValidationException
Writes changes from the bound fields to the given bean if all validators (binding and bean level) pass.
If any field binding validator fails, no values are written and a
ValidationException
is thrown.If all field level validators pass, the given bean is updated and bean level validators are run on the updated bean. If any bean level validator fails, the bean updates are reverted and a
ValidationException
is thrown.Parameters:
bean
- the object to which to write the field values, notnull
Throws:
ValidationException
- if some of the bound field values fail to validateSee Also:
-
writeBeanAsDraft
public void writeBeanAsDraft(BEAN bean)
Writes successfully converted and validated changes from the bound fields to the bean even if there are other fields with non-validated changes.
Parameters:
bean
- the object to which to write the field values, notnull
See Also:
writeBean(Object)
,writeBeanIfValid(Object)
,readBean(Object)
,setBean(Object)
-
writeBeanAsDraft
public void writeBeanAsDraft(BEAN bean, boolean forced)
Writes successfully converted changes from the bound fields bypassing all the Validation or all fields passing conversion if forced = true. If the conversion fails, the value written to the bean will be null.
Parameters:
bean
- the object to which to write the field values, notnull
forced
- disable all Validators during writeSee Also:
writeBean(Object)
,writeBeanIfValid(Object)
,readBean(Object)
,setBean(Object)
-
writeBeanIfValid
public boolean writeBeanIfValid(BEAN bean)
Writes changes from the bound fields to the given bean if all validators (binding and bean level) pass.
If any field binding validator fails, no values are written and
false
is returned.If all field level validators pass, the given bean is updated and bean level validators are run on the updated bean. If any bean level validator fails, the bean updates are reverted and
false
is returned.Parameters:
bean
- the object to which to write the field values, notnull
Returns:
true
if there was no validation errors and the bean was updated,false
otherwiseSee Also:
-
restoreBeanState
protected void restoreBeanState(BEAN bean, Map<Binder.Binding<BEAN,?>,Object> oldValues)
Restores the state of the bean from the given values.
Parameters:
bean
- the beanoldValues
- the old values
-
getBeanState
protected Map<Binder.Binding<BEAN,?>,Object> getBeanState(BEAN bean, Collection<Binder.Binding<BEAN,?>> bindings)
Stores the state of the given bean.
Parameters:
bean
- the bean to store the state ofbindings
- the bindings to storeReturns:
map from binding to value
-
withValidator
public Binder<BEAN> withValidator(Validator<? super BEAN> validator)
Adds an bean level validator.
Bean level validators are applied on the bean instance after the bean is updated. If the validators fail, the bean instance is reverted to its previous state.
Parameters:
validator
- the validator to add, not nullReturns:
this binder, for chaining
See Also:
writeBean(Object)
,writeBeanIfValid(Object)
,withValidator(SerializablePredicate, String)
,withValidator(SerializablePredicate, ErrorMessageProvider)
-
withValidator
public Binder<BEAN> withValidator(SerializablePredicate<BEAN> predicate, String message)
A convenience method to add a validator to this binder using the
Validator.from(SerializablePredicate, String)
factory method.Bean level validators are applied on the bean instance after the bean is updated. If the validators fail, the bean instance is reverted to its previous state.
Parameters:
predicate
- the predicate performing validation, not nullmessage
- the error message to report in case validation failureReturns:
this binder, for chaining
See Also:
writeBean(Object)
,writeBeanIfValid(Object)
,withValidator(Validator)
,withValidator(SerializablePredicate, ErrorMessageProvider)
-
withValidator
public Binder<BEAN> withValidator(SerializablePredicate<BEAN> predicate, ErrorMessageProvider errorMessageProvider)
A convenience method to add a validator to this binder using the
Validator.from(SerializablePredicate, ErrorMessageProvider)
factory method.Bean level validators are applied on the bean instance after the bean is updated. If the validators fail, the bean instance is reverted to its previous state.
Parameters:
predicate
- the predicate performing validation, not nullerrorMessageProvider
- the provider to generate error messages, not nullReturns:
this binder, for chaining
See Also:
writeBean(Object)
,writeBeanIfValid(Object)
,withValidator(Validator)
,withValidator(SerializablePredicate, String)
-
validate
public BinderValidationStatus<BEAN> validate()
Validates the values of all bound fields and returns the validation status.
If all field level validators pass, and
setBean(Object)
has been used to bind to a bean, bean level validators are run for that bean. Bean level validators are ignored if there is no bound bean or if any field level validator fails.Note: This method will attempt to temporarily apply all current changes to the bean and run full bean validation for it. The changes are reverted after bean validation.
Returns:
validation status for the binder
-
validate
protected BinderValidationStatus<BEAN> validate(boolean fireEvent)
Validates the values of all bound fields and returns the validation status. This method can skip firing the event, based on the given
boolean
.Parameters:
fireEvent
-true
to fire validation status events;false
to notReturns:
validation status for the binder
-
isValid
public boolean isValid()
Runs all currently configured field level validators, as well as all bean level validators if a bean is currently set with
setBean(Object)
, and returns whether any of the validators failed.Note: Calling this method will not trigger status change events, unlike
validate()
and will not modify the UI. To also update error indicators on fields, usevalidate().isOk()
.Note: This method will attempt to temporarily apply all current changes to the bean and run full bean validation for it. The changes are reverted after bean validation.
Returns:
whether this binder is in a valid state
Throws:
IllegalStateException
- if bean level validators have been configured and no bean is currently setSee Also:
-
setStatusLabel
public void setStatusLabel(HasText statusLabel)
Sets the label to show the binder level validation errors not related to any specific field.
Only the one validation error message is shown in this label at a time.
This is a convenience method for
setValidationStatusHandler(BinderValidationStatusHandler)
, which means that this method cannot be used after the handler has been set. Also the handler cannot be set after this label has been set.Parameters:
statusLabel
- the status label to setSee Also:
setValidationStatusHandler(BinderValidationStatusHandler)
,Binder.BindingBuilder.withStatusLabel(HasText)
-
getStatusLabel
public Optional<HasText> getStatusLabel()
Gets the status label or an empty optional if none has been set.
Returns:
the optional status label
See Also:
-
setValidationStatusHandler
public void setValidationStatusHandler(BinderValidationStatusHandler<BEAN> statusHandler)
Sets the status handler to track form status changes.
Setting this handler will override the default behavior, which is to let fields show their validation status messages and show binder level validation errors or OK status in the label set with
setStatusLabel(HasText)
.This handler cannot be set after the status label has been set with
setStatusLabel(HasText)
, orsetStatusLabel(HasText)
cannot be used after this handler has been set.Parameters:
statusHandler
- the status handler to set, notnull
Throws:
NullPointerException
- fornull
status handlerSee Also:
setStatusLabel(HasText)
,Binder.BindingBuilder.withValidationStatusHandler(BindingValidationStatusHandler)
-
getValidationStatusHandler
public BinderValidationStatusHandler<BEAN> getValidationStatusHandler()
Gets the status handler of this form.
If none has been set with
setValidationStatusHandler(BinderValidationStatusHandler)
, the default implementation is returned.Returns:
the status handler used, never
null
See Also:
-
addStatusChangeListener
public Registration addStatusChangeListener(StatusChangeListener listener)
Adds status change listener to the binder.
The
Binder
status is changed whenever any of the following happens:- if it's bound and any of its bound field or select has been changed
writeBean(Object)
orwriteBeanIfValid(Object)
is calledreadBean(Object)
is calledsetBean(Object)
is calledremoveBean()
is calledBinder.BindingBuilder.bind(ValueProvider, Setter)
is calledvalidate()
orBinder.Binding.validate()
is called
Parameters:
listener
- status change listener to add, not nullReturns:
a registration for the listener
See Also:
readBean(Object)
,writeBean(Object)
,writeBeanIfValid(Object)
,setBean(Object)
,removeBean()
,forField(HasValue)
,validate()
,Binder.Binding.validate()
-
addListener
protected <T> Registration addListener(Class<T> eventType, SerializableConsumer<T> method)
Adds a listener to the binder.
Type Parameters:
T
- the event typeParameters:
eventType
- the type of the eventmethod
- the consumer method of the listenerReturns:
a registration for the listener
-
addValueChangeListener
public Registration addValueChangeListener(HasValue.ValueChangeListener<? super HasValue.ValueChangeEvent<?>> listener)
Adds field value change listener to all the fields in the binder.
Added listener is notified every time whenever any bound field value is changed, i.e. the UI component value was changed, passed all the conversions and validations then propagated to the bound bean field. The same functionality can be achieved by adding a
HasValue.ValueChangeListener
to all fields in theBinder
.The listener is added to all fields regardless of whether the method is invoked before or after field is bound.
Parameters:
listener
- a field value change listenerReturns:
a registration for the listener
See Also:
-
createBinding
protected <FIELDVALUE,TARGET> Binder.BindingBuilder<BEAN,TARGET> createBinding(HasValue<?,FIELDVALUE> field, Converter<FIELDVALUE,TARGET> converter, BindingValidationStatusHandler handler)
Creates a new binding with the given field.
Type Parameters:
FIELDVALUE
- the value type of the fieldTARGET
- the target data typeParameters:
field
- the field to bind, not nullconverter
- the converter for converting between FIELDVALUE and TARGET types, not nullhandler
- the handler to notify of status changes, not nullReturns:
the new incomplete binding
-
doCreateBinding
protected <FIELDVALUE,TARGET> Binder.BindingBuilder<BEAN,TARGET> doCreateBinding(HasValue<?,FIELDVALUE> field, Converter<FIELDVALUE,TARGET> converter, BindingValidationStatusHandler handler)
-
handleError
protected void handleError(HasValue<?,?> field, ValidationResult result)
Handles a validation error emitted when trying to write the value of the given field.
Parameters:
field
- the field with the invalid valueresult
- the validation error result
-
clearError
protected void clearError(HasValue<?,?> field)
Clears the error condition of the given field, if any.
Parameters:
field
- the field with an invalid value
-
handleValidationStatus
protected void handleValidationStatus(BindingValidationStatus<?> status)
Default
BindingValidationStatusHandler
functional method implementation.Parameters:
status
- the validation status
-
getBindings
protected Collection<Binder.BindingImpl<BEAN,?,?>> getBindings()
Returns the bindings for this binder.
Returns:
a list of the bindings
-
handleBinderValidationStatus
protected void handleBinderValidationStatus(BinderValidationStatus<BEAN> binderStatus)
The default binder level status handler.
Passes all field related results to the Binding status handlers. All other status changes are displayed in the status label, if one has been set with
setStatusLabel(HasText)
.Parameters:
binderStatus
- status of validation results from binding and/or bean level validators
-
hasChanges
public boolean hasChanges()
Check whether any of the bound fields' have uncommitted changes since last explicit call to
readBean(Object)
,removeBean()
,writeBean(Object)
orwriteBeanIfValid(Object)
. Unsuccessful write operations will not affect this value.Note that if you use
setBean(Object)
method, Binder tries to commit changes as soon as all validators have passed. Thus, when using this method with it seldom makes sense and almost always returns false. Return values for each case are compiled into the following table:After readBean, setBean or removeBean After valid user changes After invalid user changes After successful writeBean or writeBeanIfValid After unsuccessful writeBean or writeBeanIfValid A bean is currently bound false
false
true
false
no change No bean is currently bound false
true
true
false
no change Returns:
whether any bound field's value has changed since last call to setBean, readBean, writeBean or writeBeanIfValid
-
setReadOnly
public void setReadOnly(boolean readOnly)
Sets the read only state to the given value for all currently bound fields.
This is just a shorthand for calling
Binder.Binding.setReadOnly(boolean)
for all current bindings. It means that bindings added after this method call won't be set read-only.Parameters:
readOnly
-true
to set the bindings to read-only,false
to set them to read-write
-
configureBinding
protected Binder.BindingBuilder<BEAN,?> configureBinding(Binder.BindingBuilder<BEAN,?> binding, PropertyDefinition<BEAN,?> definition)
Configures the
binding
with the property definitiondefinition
before it's being bound.Parameters:
binding
- a binding to configuredefinition
- a property definition informationReturns:
the new configured binding
-
bindInstanceFields
public void bindInstanceFields(Object objectWithMemberFields)
Binds member fields found in the given object.
This method processes all (Java) member fields whose type extends
HasValue
and that can be mapped to a property id. Property name mapping is done based on the field name or on a @PropertyId
annotation on the field. All non-null unbound fields for which a property name can be determined are bound to the property name usingBinder.BindingBuilder.bind(String)
.For example:
This binds the firstName TextField to a "firstName" property in the item, lastName TextField to a "last" property.public class MyForm extends VerticalLayout { private TextField firstName = new TextField("First name"); @PropertyId("last") private TextField lastName = new TextField("Last name"); MyForm myForm = new MyForm(); ... binder.bindInstanceFields(myForm);
It's not always possible to bind a field to a property because their types are incompatible. E.g. custom converter is required to bind
HasValue<String>
andInteger
property (that would be a case of "age" property). In such caseIllegalStateException
will be thrown unless the field has been configured manually before calling thebindInstanceFields(Object)
method.It's always possible to do custom binding for any field: the
bindInstanceFields(Object)
method doesn't override existing bindings.Parameters:
objectWithMemberFields
- The object that contains (Java) member fields to bindThrows:
IllegalStateException
- if there are incompatible HasValue<T> and property types
-
getBinding
public Optional<Binder.Binding<BEAN,?>> getBinding(String propertyName)
Gets the binding for a property name. Bindings are available by property name if bound using
bind(HasValue, String)
,Binder.BindingBuilder.bind(String)
or indirectly usingbindInstanceFields(Object)
.Parameters:
propertyName
- the property name of the binding to getReturns:
the binding corresponding to the property name, or an empty optional if there is no binding with that property name
-
getFields
public Stream<HasValue<?,?>> getFields()
Returns the fields this binder has been bound to.
Returns:
the fields with bindings
-
removeBinding
public void removeBinding(HasValue<?,?> field)
Finds and removes all Bindings for the given field.
Parameters:
field
- the field to remove from bindings
-
removeBinding
public void removeBinding(Binder.Binding<BEAN,?> binding)
Removes the given Binding from this Binder.
Parameters:
binding
- the binding to remove
-
removeBindingInternal
protected void removeBindingInternal(Binder.Binding<BEAN,?> binding)
Removes (internally) the
Binding
from the bound properties map (if present) and from the list ofBinding
s. Note that this DOES NOT remove theValueChangeListener
that theBinding
might have registered with anyHasValue
s or decouple theBinder
from within theBinding
. To do that, useBinder.Binding.unbind()
This method should just be used for internal cleanup.Parameters:
binding
- TheBinding
to remove from the binding map
-
removeBinding
public void removeBinding(String propertyName)
Finds and removes the Binding for the given property name.
Parameters:
propertyName
- the propertyName to remove from bindings
-
setValidatorsDisabled
public void setValidatorsDisabled(boolean validatorsDisabled)
Control whether validators including bean level validators are disabled or enabled globally for this Binder.
Parameters:
validatorsDisabled
- Boolean value.
-
isValidatorsDisabled
public boolean isValidatorsDisabled()
Returns if the validators including bean level validators are disabled or enabled for this Binder.
Returns:
Boolean value
-
-