BEAN
- the bean typeTARGET
- the target data type of the binding, matches the field type
until a converter has been setpublic static interface Binder.BindingBuilder<BEAN,TARGET> extends Serializable
Binder.forField(HasValue)
Modifier and Type | Method and 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.
|
default Binder.BindingBuilder<BEAN,TARGET> |
asRequired(String errorMessage)
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.
|
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> |
bind(ValueProvider<BEAN,TARGET> getter,
Setter<BEAN,TARGET> setter)
Completes this binding using the given getter and setter functions
representing a backing bean property.
|
HasValue<?,?> |
getField()
Gets the field the binding is being built for.
|
<NEWTARGET> |
withConverter(Converter<TARGET,NEWTARGET> converter)
Maps the binding to another data type using the given
Converter . |
default <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> |
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. |
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. |
Binder.BindingBuilder<BEAN,TARGET> |
withValidator(Validator<? super TARGET> validator)
Adds a validator to this binding.
|
HasValue<?,?> getField()
Binder.Binding<BEAN,TARGET> bind(ValueProvider<BEAN,TARGET> getter, Setter<BEAN,TARGET> setter)
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
ValidationStatusChangeEvent
s 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)
.
getter
- 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-onlyIllegalStateException
- if bind
has already been called on this bindingBinder.Binding<BEAN,TARGET> bind(String propertyName)
PropertySet
.
For a Binder
created using the
Binder.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)
.
propertyName
- the name of the property to bind, not nullIllegalArgumentException
- if the property name is invalidIllegalArgumentException
- if the property has no accessible getterIllegalStateException
- if the binder is not configured with an appropriate
PropertySet
bind(ValueProvider, Setter)
Binder.BindingBuilder<BEAN,TARGET> withValidator(Validator<? super TARGET> validator)
validator
- the validator to add, not nullIllegalStateException
- if bind
has already been calledwithValidator(SerializablePredicate, String)
,
withValidator(SerializablePredicate, ErrorMessageProvider)
default Binder.BindingBuilder<BEAN,TARGET> withValidator(SerializablePredicate<? super TARGET> predicate, String message)
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.
predicate
- the predicate performing validation, not nullmessage
- the error message to report in case validation failureIllegalStateException
- if bind
has already been calledwithValidator(Validator)
,
withValidator(SerializablePredicate, String, ErrorLevel)
,
withValidator(SerializablePredicate, ErrorMessageProvider)
,
Validator.from(SerializablePredicate, String)
default Binder.BindingBuilder<BEAN,TARGET> withValidator(SerializablePredicate<? super TARGET> predicate, String message, ErrorLevel errorLevel)
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.
predicate
- the predicate performing validation, not nullmessage
- the error message to report in case validation failureerrorLevel
- the error level for failures from this validator, not nullIllegalStateException
- if bind
has already been calledwithValidator(Validator)
,
withValidator(SerializablePredicate, String)
,
withValidator(SerializablePredicate, ErrorMessageProvider,
ErrorLevel)
,
Validator.from(SerializablePredicate, String)
default Binder.BindingBuilder<BEAN,TARGET> withValidator(SerializablePredicate<? super TARGET> predicate, ErrorMessageProvider errorMessageProvider)
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.
predicate
- the predicate performing validation, not nullerrorMessageProvider
- the provider to generate error messages, not nullIllegalStateException
- if bind
has already been calledwithValidator(Validator)
,
withValidator(SerializablePredicate, String)
,
withValidator(SerializablePredicate, ErrorMessageProvider,
ErrorLevel)
,
Validator.from(SerializablePredicate, ErrorMessageProvider)
default Binder.BindingBuilder<BEAN,TARGET> withValidator(SerializablePredicate<? super TARGET> predicate, ErrorMessageProvider errorMessageProvider, ErrorLevel errorLevel)
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.
predicate
- the predicate performing validation, not nullerrorMessageProvider
- the provider to generate error messages, not nullerrorLevel
- the error level for failures from this validator, not nullIllegalStateException
- if bind
has already been calledwithValidator(Validator)
,
withValidator(SerializablePredicate, String, ErrorLevel)
,
withValidator(SerializablePredicate, ErrorMessageProvider)
,
Validator.from(SerializablePredicate, ErrorMessageProvider,
ErrorLevel)
<NEWTARGET> Binder.BindingBuilder<BEAN,NEWTARGET> withConverter(Converter<TARGET,NEWTARGET> converter)
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 not applied back to the field by default, this
can be controlled with the method
Binder.Binding.setConvertBackToPresentation(boolean)
.
NEWTARGET
- the type to convert toconverter
- the converter to use, not nullIllegalStateException
- if bind
has already been calledBinder.Binding.setConvertBackToPresentation(boolean)
default <NEWTARGET> Binder.BindingBuilder<BEAN,NEWTARGET> withConverter(SerializableFunction<TARGET,NEWTARGET> toModel, SerializableFunction<NEWTARGET,TARGET> toPresentation)
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 not applied back to the field by default, this
can be controlled with the method
Binder.Binding.setConvertBackToPresentation(boolean)
.
NEWTARGET
- the type to convert totoModel
- the function which can convert from the old target type to
the new target typetoPresentation
- the function which can convert from the new target type to
the old target typeIllegalStateException
- if bind
has already been calledBinder.Binding.setConvertBackToPresentation(boolean)
default <NEWTARGET> Binder.BindingBuilder<BEAN,NEWTARGET> withConverter(SerializableFunction<TARGET,NEWTARGET> toModel, SerializableFunction<NEWTARGET,TARGET> toPresentation, String errorMessage)
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 not applied back to the field by default, this
can be controlled with the method
Binder.Binding.setConvertBackToPresentation(boolean)
.
NEWTARGET
- the type to convert totoModel
- the function which can convert from the old target type to
the new target typetoPresentation
- the function which can convert from the new target type to
the old target typeerrorMessage
- the error message to use if conversion using
toModel
failsIllegalStateException
- if bind
has already been calledBinder.Binding.setConvertBackToPresentation(boolean)
default Binder.BindingBuilder<BEAN,TARGET> withNullRepresentation(TARGET nullRepresentation)
null
to given null representation and back
to null
when converting back to model value.nullRepresentation
- the value to use instead of null
default Binder.BindingBuilder<BEAN,TARGET> withStatusLabel(HasText label)
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.
label
- label to show validation status for the fieldwithValidationStatusHandler(BindingValidationStatusHandler)
Binder.BindingBuilder<BEAN,TARGET> withValidationStatusHandler(BindingValidationStatusHandler handler)
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.
handler
- status change handlerwithStatusLabel(HasText)
default Binder.BindingBuilder<BEAN,TARGET> asRequired(String errorMessage)
asRequired(ErrorMessageProvider)
.
*Value not being the equal to what HasValue.getEmptyValue()
returns.
errorMessage
- the error message to show for the invalid valueasRequired(ErrorMessageProvider)
,
HasValue.setRequiredIndicatorVisible(boolean)
,
HasValue.isEmpty()
default Binder.BindingBuilder<BEAN,TARGET> asRequired()
HasValue.getEmptyValue()
returns
For setting an error message, use asRequired(String)
.
For localizing the error message, use
asRequired(ErrorMessageProvider)
.
asRequired(String)
,
asRequired(ErrorMessageProvider)
,
HasValue.setRequiredIndicatorVisible(boolean)
,
HasValue.isEmpty()
Binder.BindingBuilder<BEAN,TARGET> asRequired(ErrorMessageProvider errorMessageProvider)
HasValue.getEmptyValue()
returns.errorMessageProvider
- the provider for localized validation error messageHasValue.setRequiredIndicatorVisible(boolean)
,
HasValue.isEmpty()
Binder.BindingBuilder<BEAN,TARGET> asRequired(Validator<TARGET> customRequiredValidator)
customRequiredValidator
- validator responsible for the required checkHasValue.setRequiredIndicatorVisible(boolean)
Copyright © 2025. All rights reserved.