Package com.vaadin.flow.data.binder

Interface Binder.BindingBuilder<BEAN,TARGET>

Type Parameters:

BEAN - the bean type

TARGET - the target data type of the binding, matches the field type until a converter has been set

All Superinterfaces:

Serializable

All Known Implementing Classes:

Binder.BindingBuilderImpl, CollaborationBinder.CollaborationBindingBuilderImpl

Enclosing class:

Binder<BEAN>

public static interface Binder.BindingBuilder<BEAN,TARGET>
extends Serializable

Creates a binding between a field and a data property.

See Also:

• Binder.forField(HasValue)

Method Summary

Modifier and Type	Method	Description
default Binder.BindingBuilder<BEAN,TARGET>	asRequired()	Sets the field to be required.
Binder.BindingBuilder<BEAN,TARGET>	asRequired(ErrorMessageProvider errorMessageProvider)	Sets the field to be required.
Binder.BindingBuilder<BEAN,TARGET>	asRequired(Validator<TARGET> customRequiredValidator)	Sets the field to be required and delegates the required check to a custom validator.
default Binder.BindingBuilder<BEAN,TARGET>	asRequired(String errorMessage)	Sets the field to be required.
Binder.Binding<BEAN,TARGET>	bind(ValueProvider<BEAN,TARGET> getter, Setter<BEAN,TARGET> setter)	Completes this binding using the given getter and setter functions representing a backing bean property.
Binder.Binding<BEAN,TARGET>	bind(String propertyName)	Completes this binding by connecting the field to the property with the given name.
Binder.Binding<BEAN,TARGET>	bindReadOnly(ValueProvider<BEAN,TARGET> getter)	Completes this binding using the given getter function representing a backing bean property.
Binder.Binding<BEAN,TARGET>	bindReadOnly(String propertyName)	Completes this binding by connecting the field to the property with the given name.
HasValue<?,?>	getField()	Gets the field the binding is being built for.
<NEWTARGET> Binder.BindingBuilder<BEAN,NEWTARGET>	withConverter(Converter<TARGET,NEWTARGET> converter)	Maps the binding to another data type using the given Converter.
default <NEWTARGET> Binder.BindingBuilder<BEAN,NEWTARGET>	withConverter(SerializableFunction<TARGET,NEWTARGET> toModel, SerializableFunction<NEWTARGET,TARGET> toPresentation)	Maps the binding to another data type using the mapping functions and a possible exception as the error message.
default <NEWTARGET> Binder.BindingBuilder<BEAN,NEWTARGET>	withConverter(SerializableFunction<TARGET,NEWTARGET> toModel, SerializableFunction<NEWTARGET,TARGET> toPresentation, String errorMessage)	Maps the binding to another data type using the mapping functions and the given error error message if a value cannot be converted to the new target type.
default Binder.BindingBuilder<BEAN,TARGET>	withNullRepresentation(TARGET nullRepresentation)	Maps binding value null to given null representation and back to null when converting back to model value.
default Binder.BindingBuilder<BEAN,TARGET>	withStatusLabel(HasText label)	Sets the given label to show an error message if validation fails.
Binder.BindingBuilder<BEAN,TARGET>	withValidationStatusHandler(BindingValidationStatusHandler handler)	Sets a BindingValidationStatusHandler to track validation status changes.
Binder.BindingBuilder<BEAN,TARGET>	withValidator(Validator<? super TARGET> validator)	Adds a validator to this binding.
default Binder.BindingBuilder<BEAN,TARGET>	withValidator(SerializablePredicate<? super TARGET> predicate, ErrorMessageProvider errorMessageProvider)	A convenience method to add a validator to this binding using the Validator.from(SerializablePredicate, ErrorMessageProvider) factory method.
default Binder.BindingBuilder<BEAN,TARGET>	withValidator(SerializablePredicate<? super TARGET> predicate, ErrorMessageProvider errorMessageProvider, ErrorLevel errorLevel)	A convenience method to add a validator to this binding using the Validator.from(SerializablePredicate, ErrorMessageProvider, ErrorLevel) factory method.
default Binder.BindingBuilder<BEAN,TARGET>	withValidator(SerializablePredicate<? super TARGET> predicate, String message)	A convenience method to add a validator to this binding using the Validator.from(SerializablePredicate, String) factory method.
default Binder.BindingBuilder<BEAN,TARGET>	withValidator(SerializablePredicate<? super TARGET> predicate, String message, ErrorLevel errorLevel)	A convenience method to add a validator to this binding using the Validator.from(SerializablePredicate, String, ErrorLevel) factory method.

Method Details

getField

HasValue<?,?> getField()

Gets the field the binding is being built for.

Returns:

the field this binding is being built for

bind

Binder.Binding<BEAN,TARGET> bind(ValueProvider<BEAN,TARGET> getter,
 Setter<BEAN,TARGET> setter)

Completes this binding using the given getter and setter functions representing a backing bean property. The functions are used to update the field value from the property and to store the field value to the property, respectively.

When a bean is bound with Binder.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.

If the bound field implements HasValidator, then the binding instance returned by this method will subscribe for field's ValidationStatusChangeEvents and will validate itself upon receiving them.

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.forField(nameField).bind(Person::getName, Person::setName);
 

Note: when a null setter is given the field will be marked as readonly by invoking HasValue.setReadOnly(boolean).

Parameters:

getter - the function to get the value of the property to the field, not null

setter - the function to write the field value to the property or null if read-only

Returns:

the newly created binding

Throws:

IllegalStateException - if bind has already been called on this binding

bindReadOnly

Binder.Binding<BEAN,TARGET> bindReadOnly(ValueProvider<BEAN,TARGET> getter)

Completes this binding using the given getter function representing a backing bean property. The function is used to update the field value from the property. The field value is not written back to the bean so the binding is read-only.

When a bean is bound with Binder.setBean(Object), the field value is set to the return value of the given getter.

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 can be arbitrary functions, for instance implementing user-defined conversion or validation. However, in the most basic use case you can simply a method references to this method as follows:

 class Person {
     public String getName() { ... }
 }

 TextField nameField = new TextField();
 binder.forField(nameField).bindReadOnly(Person::getName);
 

Note: the field will be marked as readonly by invoking HasValue.setReadOnly(boolean).

This is a shorthand for bind(ValueProvider, Setter) method called with null setter.

Parameters:

getter - the function to get the value of the property to the field, not null

Returns:

the newly created binding

Throws:

IllegalStateException - if bind has already been called on this binding

See Also:

• bind(ValueProvider, Setter)

bind

Binder.Binding<BEAN,TARGET> bind(String propertyName)

Completes this binding by connecting the 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 the Binder(Class) constructor, introspection will be used to find a Java Bean property. If a JSR-303 bean validation implementation is present on the classpath, a BeanValidator 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. Nested property, when supported, can be referenced using the bean path, starting from the root class, for example 'address.streetName'. All intermediate getters must exist (e.g. getAddress()), and should never return null, otherwise binding will fail.

Note: when the binding is read-only the field will be marked as readonly by invoking HasValue.setReadOnly(boolean).

Parameters:

propertyName - the name of the property to bind, not null

Returns:

the newly created binding

Throws:

IllegalArgumentException - if the property name is invalid

IllegalArgumentException - if the property has no accessible getter

IllegalStateException - if the binder is not configured with an appropriate PropertySet

See Also:

• bind(ValueProvider, Setter)

bindReadOnly

Binder.Binding<BEAN,TARGET> bindReadOnly(String propertyName)

Completes this binding by connecting the field to the property with the given name. The getter of the property is looked up using a PropertySet. The field value is not written back to the bean so the binding is read-only.

For a Binder created using the Binder(Class) constructor, introspection will be used to find a Java Bean property. If a JSR-303 bean validation implementation is present on the classpath, a BeanValidator is also added to the binding.

The property must have an accessible getter method. Nested property, when supported, can be referenced using the bean path, starting from the root class, for example 'address.streetName'. All intermediate getters must exist (e.g. getAddress()), and should never return null, otherwise binding will fail.

Note: the field will be marked as readonly by invoking HasValue.setReadOnly(boolean).

Parameters:

propertyName - the name of the property to bind, not null

Returns:

the newly created binding

Throws:

IllegalArgumentException - if the property name is invalid

IllegalArgumentException - if the property has no accessible getter

IllegalStateException - if the binder is not configured with an appropriate PropertySet

See Also:

• bind(String)
• bind(ValueProvider, Setter)

withValidator

Binder.BindingBuilder<BEAN,TARGET> withValidator(Validator<? super TARGET> validator)

Adds a validator to this binding. Validators are applied, in registration order, when the field value is written to the backing property. If any validator returns a failure, the property value is not updated.

Parameters:

validator - the validator to add, not null

Returns:

this binding, for chaining

Throws:

IllegalStateException - if bind has already been called

See Also:

• withValidator(SerializablePredicate, String)
• withValidator(SerializablePredicate, ErrorMessageProvider)

withValidator

default Binder.BindingBuilder<BEAN,TARGET> withValidator(SerializablePredicate<? super TARGET> predicate,
 String message)

A convenience method to add a validator to this binding using the Validator.from(SerializablePredicate, String) factory method.

Validators are applied, in registration order, when the field value is written to the backing property. If any validator returns a failure, the property value is not updated.

Parameters:

predicate - the predicate performing validation, not null

message - the error message to report in case validation failure

Returns:

this binding, for chaining

Throws:

IllegalStateException - if bind has already been called

See Also:

• withValidator(Validator)
• withValidator(SerializablePredicate, String, ErrorLevel)
• withValidator(SerializablePredicate, ErrorMessageProvider)
• Validator.from(SerializablePredicate, String)

withValidator

default Binder.BindingBuilder<BEAN,TARGET> withValidator(SerializablePredicate<? super TARGET> predicate,
 String message,
 ErrorLevel errorLevel)

A convenience method to add a validator to this binding using the Validator.from(SerializablePredicate, String, ErrorLevel) factory method.

Validators are applied, in registration order, when the field value is written to the backing property. If any validator returns a failure, the property value is not updated.

Parameters:

predicate - the predicate performing validation, not null

message - the error message to report in case validation failure

errorLevel - the error level for failures from this validator, not null

Returns:

this binding, for chaining

Throws:

IllegalStateException - if bind has already been called

See Also:

• withValidator(Validator)
• withValidator(SerializablePredicate, String)
• withValidator(SerializablePredicate, ErrorMessageProvider, ErrorLevel)
• Validator.from(SerializablePredicate, String)

withValidator

default Binder.BindingBuilder<BEAN,TARGET> withValidator(SerializablePredicate<? super TARGET> predicate,
 ErrorMessageProvider errorMessageProvider)

A convenience method to add a validator to this binding using the Validator.from(SerializablePredicate, ErrorMessageProvider) factory method.

Validators are applied, in registration order, when the field value is written to the backing property. If any validator returns a failure, the property value is not updated.

Parameters:

predicate - the predicate performing validation, not null

errorMessageProvider - the provider to generate error messages, not null

Returns:

this binding, for chaining

Throws:

IllegalStateException - if bind has already been called

See Also:

• withValidator(Validator)
• withValidator(SerializablePredicate, String)
• withValidator(SerializablePredicate, ErrorMessageProvider, ErrorLevel)
• Validator.from(SerializablePredicate, ErrorMessageProvider)

withValidator

default Binder.BindingBuilder<BEAN,TARGET> withValidator(SerializablePredicate<? super TARGET> predicate,
 ErrorMessageProvider errorMessageProvider,
 ErrorLevel errorLevel)

A convenience method to add a validator to this binding using the Validator.from(SerializablePredicate, ErrorMessageProvider, ErrorLevel) factory method.

Validators are applied, in registration order, when the field value is written to the backing property. If any validator returns a failure, the property value is not updated.

Parameters:

predicate - the predicate performing validation, not null

errorMessageProvider - the provider to generate error messages, not null

errorLevel - the error level for failures from this validator, not null

Returns:

this binding, for chaining

Throws:

IllegalStateException - if bind has already been called

See Also:

• withValidator(Validator)
• withValidator(SerializablePredicate, String, ErrorLevel)
• withValidator(SerializablePredicate, ErrorMessageProvider)
• Validator.from(SerializablePredicate, ErrorMessageProvider, ErrorLevel)

withConverter

<NEWTARGET> Binder.BindingBuilder<BEAN,NEWTARGET> withConverter(Converter<TARGET,NEWTARGET> converter)

Maps the binding to another data type using the given Converter.

A converter is capable of converting between a presentation type, which must match the current target data type of the binding, and a model type, which can be any data type and becomes the new target type of the binding. When invoking bind(ValueProvider, Setter), the target type of the binding must match the getter/setter types.

For instance, a TextField can be bound to an integer-typed property using an appropriate converter such as a StringToIntegerConverter.

The converted value is applied back to the field by default, this can be controlled with the method Binder.Binding.setConvertBackToPresentation(boolean).

Type Parameters:

NEWTARGET - the type to convert to

Parameters:

converter - the converter to use, not null

Returns:

a new binding with the appropriate type

Throws:

IllegalStateException - if bind has already been called

See Also:

• Binder.Binding.setConvertBackToPresentation(boolean)

withConverter

default <NEWTARGET>
Binder.BindingBuilder<BEAN,NEWTARGET> withConverter(SerializableFunction<TARGET,NEWTARGET> toModel,
 SerializableFunction<NEWTARGET,TARGET> toPresentation)

Maps the binding to another data type using the mapping functions and a possible exception as the error message.

The mapping functions are used to convert between a presentation type, which must match the current target data type of the binding, and a model type, which can be any data type and becomes the new target type of the binding. When invoking bind(ValueProvider, Setter), the target type of the binding must match the getter/setter types.

For instance, a TextField can be bound to an integer-typed property using appropriate functions such as: withConverter(Integer::valueOf, String::valueOf);

The converted value is applied back to the field by default, this can be controlled with the method Binder.Binding.setConvertBackToPresentation(boolean).

Type Parameters:

NEWTARGET - the type to convert to

Parameters:

toModel - the function which can convert from the old target type to the new target type

toPresentation - the function which can convert from the new target type to the old target type

Returns:

a new binding with the appropriate type

Throws:

IllegalStateException - if bind has already been called

See Also:

• Binder.Binding.setConvertBackToPresentation(boolean)

withConverter

default <NEWTARGET>
Binder.BindingBuilder<BEAN,NEWTARGET> withConverter(SerializableFunction<TARGET,NEWTARGET> toModel,
 SerializableFunction<NEWTARGET,TARGET> toPresentation,
 String errorMessage)

Maps the binding to another data type using the mapping functions and the given error error message if a value cannot be converted to the new target type.

The mapping functions are used to convert between a presentation type, which must match the current target data type of the binding, and a model type, which can be any data type and becomes the new target type of the binding. When invoking bind(ValueProvider, Setter), the target type of the binding must match the getter/setter types.

For instance, a TextField can be bound to an integer-typed property using appropriate functions such as: withConverter(Integer::valueOf, String::valueOf);

The converted value is applied back to the field by default, this can be controlled with the method Binder.Binding.setConvertBackToPresentation(boolean).

Type Parameters:

NEWTARGET - the type to convert to

Parameters:

toModel - the function which can convert from the old target type to the new target type

toPresentation - the function which can convert from the new target type to the old target type

errorMessage - the error message to use if conversion using toModel fails

Returns:

a new binding with the appropriate type

Throws:

IllegalStateException - if bind has already been called

See Also:

• Binder.Binding.setConvertBackToPresentation(boolean)

withNullRepresentation

default Binder.BindingBuilder<BEAN,TARGET> withNullRepresentation(TARGET nullRepresentation)

Maps binding value null to given null representation and back to null when converting back to model value.

Parameters:

nullRepresentation - the value to use instead of null

Returns:

a new binding with null representation handling.

withStatusLabel

default Binder.BindingBuilder<BEAN,TARGET> withStatusLabel(HasText label)

Sets the given label to show an error message if validation fails.

The validation state of each field is updated whenever the user modifies the value of that field.

This method allows to customize the way a binder displays error messages.

This is just a shorthand for withValidationStatusHandler(BindingValidationStatusHandler) method where the handler instance hides the label if there is no error and shows it with validation error message if validation fails. It means that it cannot be called after withValidationStatusHandler(BindingValidationStatusHandler) method call or withValidationStatusHandler(BindingValidationStatusHandler) after this method call.

Parameters:

label - label to show validation status for the field

Returns:

this binding, for chaining

See Also:

• withValidationStatusHandler(BindingValidationStatusHandler)

withValidationStatusHandler

Binder.BindingBuilder<BEAN,TARGET> withValidationStatusHandler(BindingValidationStatusHandler handler)

Sets a BindingValidationStatusHandler to track validation status changes.

The validation state of each field is updated whenever the user modifies the value of that field.

This method allows to customize the way a binder displays error messages.

The method may be called only once. It means there is no chain unlike withValidator(Validator) or withConverter(Converter). Also it means that the shorthand method withStatusLabel(HasText) also may not be called after this method.

Parameters:

handler - status change handler

Returns:

this binding, for chaining

See Also:

• withStatusLabel(HasText)

asRequired

default Binder.BindingBuilder<BEAN,TARGET> asRequired(String errorMessage)

Sets the field to be required. This means two things:

1. the required indicator is visible
2. the field value is validated for not being empty*

For localizing the error message, use asRequired(ErrorMessageProvider).

*Value not being the equal to what HasValue.getEmptyValue() returns.

Parameters:

errorMessage - the error message to show for the invalid value

Returns:

this binding, for chaining

See Also:

• asRequired(ErrorMessageProvider)
• HasValue.setRequiredIndicatorVisible(boolean)
• HasValue.isEmpty()

asRequired

default Binder.BindingBuilder<BEAN,TARGET> asRequired()

Sets the field to be required. This means two things:

1. the required indicator will be displayed for this field
2. the field value is validated for not being empty, i.e. that the field's value is not equal to what HasValue.getEmptyValue() returns

For setting an error message, use asRequired(String).

For localizing the error message, use asRequired(ErrorMessageProvider).

Returns:

this binding, for chaining

See Also:

• asRequired(String)
• asRequired(ErrorMessageProvider)
• HasValue.setRequiredIndicatorVisible(boolean)
• HasValue.isEmpty()

asRequired

Binder.BindingBuilder<BEAN,TARGET> asRequired(ErrorMessageProvider errorMessageProvider)

Sets the field to be required. This means two things:

1. the required indicator is visible
2. the field value is validated for not being empty*

*Value not being the equal to what HasValue.getEmptyValue() returns.

Parameters:

errorMessageProvider - the provider for localized validation error message

Returns:

this binding, for chaining

See Also:

• HasValue.setRequiredIndicatorVisible(boolean)
• HasValue.isEmpty()

asRequired

Binder.BindingBuilder<BEAN,TARGET> asRequired(Validator<TARGET> customRequiredValidator)

Sets the field to be required and delegates the required check to a custom validator. This means two things:

1. the required indicator will be displayed for this field
2. the field value is validated by customRequiredValidator

Parameters:

customRequiredValidator - validator responsible for the required check

Returns:

this binding, for chaining

See Also:

• HasValue.setRequiredIndicatorVisible(boolean)