com.holonplatform.vaadin.components

## Interface PropertyInputGroup

- All Superinterfaces:
    PropertySetBound, Serializable, Validatable, ValueHolder<com.holonplatform.core.property.PropertyBox>
  All Known Subinterfaces:
    PropertyInputForm

      public interface PropertyInputGroup
      extends PropertySetBound, ValueHolder<com.holonplatform.core.property.PropertyBox>, Validatable

  A class to manage a group of `Input`s bound to a `Property` set, loading and obtaining property values in and from `Input`s using the `PropertyBox` data container type.

  Supports overall `Validator`s registration to validate all the `Input` values, allowing cross input validation, using a `PropertyBox` to represent the inputs value set.

  By default, property `Input` components are obtained from the `PropertyRenderer`s registered in the context `PropertyRendererRegistry`, if available. Custom `PropertyRenderer` registration is supported to provide a custom behaviour for specific properties.

  Default property values are supported using a `PropertyInputGroup.DefaultValueProvider`. The property default values are loaded when `ValueHolder.clear()` or `setValue(PropertyBox)` methods are invoked.

  Convenience methods `setEnabled(boolean)` and `setReadOnly(boolean)` can be used to change the enabled / read-only state for all the property bound `Input`s.

  Since:
    5.0.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `PropertyInputGroup.Builder<G extends PropertyInputGroup,B extends PropertyInputGroup.Builder<G,B>>` Base `PropertyInputGroup` builder.
    `static interface` | `PropertyInputGroup.DefaultValueProvider<T>` Interface to provide the default value for a `Property`.
    `static class` | `PropertyInputGroup.OverallValidationException` `Validator.ValidationException` extension to discern inputs validation and overall container validation exceptions.
    `static interface` | `PropertyInputGroup.PropertyInputGroupBuilder` `PropertyInputGroup` builder.

    - ### Nested classes/interfaces inherited from interface com.holonplatform.vaadin.components.ValueHolder

      `ValueHolder.ValueChangeEvent<V>, ValueHolder.ValueChangeListener<V>`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `static PropertyInputGroup.PropertyInputGroupBuilder` | `builder()` Get a `PropertyInputGroup.Builder` to create and setup a `PropertyInputGroup`.
    `<T> Optional<Input<T>>` | `getInput(com.holonplatform.core.property.Property<T> property)` Get the `Input` bound to given `property`, if any.
    `Iterable<Input<?>>` | `getInputs()` Gets all the `Input`s that have been bound to a property.
    `default com.holonplatform.core.property.PropertyBox` | `getValue()` Get the current property values collected into a `PropertyBox`, using the group configured properties as property set.
    `com.holonplatform.core.property.PropertyBox` | `getValue(boolean validate)` Get the current property values collected into a `PropertyBox`, using the group configured properties as property set.
    `Optional<com.holonplatform.core.property.PropertyBox>` | `getValueIfValid()` Get the current property values collected into a `PropertyBox`, using the group configured properties as property set, only if the property bound `Input`s and this `PropertyInputGroup` are valid For each property with a bound `Input` component, the property value is obtained from the `Input` component through the `ValueHolder.getValue()` method.
    `void` | `setEnabled(boolean enabled)` Updates the enabled state of all the group inputs.
    `void` | `setReadOnly(boolean readOnly)` Set the read-only mode for all the group inputs.
    `default void` | `setValue(com.holonplatform.core.property.PropertyBox propertyBox)` Set the current property values using a `PropertyBox`, loading the values to the available property bound `Input`s through the `ValueHolder.setValue(Object)` method.
    `void` | `setValue(com.holonplatform.core.property.PropertyBox propertyBox, boolean validate)` Set the current property values using a `PropertyBox`, loading the values to the available property bound `Input`s through the `ValueHolder.setValue(Object)` method.
    `<T> Stream<PropertyBinding<T,Input<T>>>` | `stream()` Return a `Stream` of the properties and their bound `Input`s of this input group.

    - ### Methods inherited from interface com.holonplatform.vaadin.components.PropertySetBound

      `getProperties, hasProperty, propertyStream`

    - ### Methods inherited from interface com.holonplatform.vaadin.components.ValueHolder

      `addValueChangeListener, clear, getEmptyValue, getOptionalValue, isEmpty`

    - ### Methods inherited from interface com.holonplatform.vaadin.components.Validatable

      `isValid, validate`

- - ### Method Detail

    - #### getInputs

          Iterable<Input<?>> getInputs()

      Gets all the `Input`s that have been bound to a property.
      Returns:
        An `Iterable` on all bound `Input`s

    - #### getInput

          <T> Optional<Input<T>> getInput(com.holonplatform.core.property.Property<T> property)

      Get the `Input` bound to given `property`, if any.
      Type Parameters:
        `T` - Property type
      Parameters:
        `property` - Property for which to get the associated `Input` (not null)
      Returns:
        Optional `Input` bound to given `property`

    - #### stream

          <T> Stream<PropertyBinding<T,Input<T>>> stream()

      Return a `Stream` of the properties and their bound `Input`s of this input group.
      Type Parameters:
        `T` - Property type
      Returns:
        Property-Input `PropertyBinding` stream

    - #### getValue

          com.holonplatform.core.property.PropertyBox getValue(boolean validate)

      Get the current property values collected into a `PropertyBox`, using the group configured properties as property set.

      For each property with a bound `Input` component, the property value is obtained from the `Input` component through the `ValueHolder.getValue()` method.

      Parameters:
        `validate` - `true` to check the validity of the property bound `Input`s and of this `PropertyInputGroup` before returing the value, throwing a `Validator.ValidationException` if the validation is not successful.
      Returns:
        A `PropertyBox` containing the property values (never null)
      Throws:
        `com.holonplatform.core.Validator.ValidationException` - If `validate` is `true` and an `Input` value is not valid
        `PropertyInputGroup.OverallValidationException` - If the overall validation failed

    - #### getValue

          default com.holonplatform.core.property.PropertyBox getValue()

      Get the current property values collected into a `PropertyBox`, using the group configured properties as property set.

      For each property with a bound `Input` component, the property value is obtained from the `Input` component through the `ValueHolder.getValue()` method.

      The available `Input`s and the overall group validation is performed before returning the value, throwing a `Validator.ValidationException` if the validation is not successful.

      Specified by:
        `getValue` in interface `ValueHolder<com.holonplatform.core.property.PropertyBox>`
      Returns:
        A `PropertyBox` containing the property values (never null)
      Throws:
        `com.holonplatform.core.Validator.ValidationException` - If one or more input value is not valid, providing the validation error messages
        `PropertyInputGroup.OverallValidationException` - If the overall validation failed
      See Also:
        `getValue(boolean)`, `getValueIfValid()`

    - #### getValueIfValid

          Optional<com.holonplatform.core.property.PropertyBox> getValueIfValid()

      Get the current property values collected into a `PropertyBox`, using the group configured properties as property set, only if the property bound `Input`s and this `PropertyInputGroup` are valid

      For each property with a bound `Input` component, the property value is obtained from the `Input` component through the `ValueHolder.getValue()` method.

      Returns:
        A `PropertyBox` containing the property values, or an empty Optional if validation failed

    - #### setValue

          void setValue(com.holonplatform.core.property.PropertyBox propertyBox,
                        boolean validate)

      Set the current property values using a `PropertyBox`, loading the values to the available property bound `Input`s through the `ValueHolder.setValue(Object)` method.

      Only the properties which belong to the group's property set are taken into account.

      Parameters:
        `propertyBox` - the `PropertyBox` which contains the property values to load. If `null`, all the `Input` components are cleared.
        `validate` - `true` to check the validity of the property bound `Input`s and of this `PropertyInputGroup`, throwing a `Validator.ValidationException` if the validation is not successful.
      Throws:
        `com.holonplatform.core.Validator.ValidationException` - If `validate` is `true` and an `Input` value is not valid
        `PropertyInputGroup.OverallValidationException` - If overall validation failed

    - #### setValue

          default void setValue(com.holonplatform.core.property.PropertyBox propertyBox)

      Set the current property values using a `PropertyBox`, loading the values to the available property bound `Input`s through the `ValueHolder.setValue(Object)` method.

      Only the properties which belong to the group's property set are taken into account.

      By default, no value validation is performed using this method.

      Specified by:
        `setValue` in interface `ValueHolder<com.holonplatform.core.property.PropertyBox>`
      Parameters:
        `propertyBox` - the `PropertyBox` which contains the property values to load. If `null`, all the `Input` components are cleared.
      See Also:
        `setValue(PropertyBox, boolean)`

    - #### setReadOnly

          void setReadOnly(boolean readOnly)

      Set the read-only mode for all the group inputs.
      Parameters:
        `readOnly` - `true` to set all inputs as read-only, `false` to unset

    - #### setEnabled

          void setEnabled(boolean enabled)

      Updates the enabled state of all the group inputs.
      Parameters:
        `enabled` - `true` to enable all group inputs, `false` to disable them

    - #### builder

          static PropertyInputGroup.PropertyInputGroupBuilder builder()

      Get a `PropertyInputGroup.Builder` to create and setup a `PropertyInputGroup`.
      Returns:
        `PropertyInputGroup` builder

Copyright © 2017 The Holon Platform. All rights reserved.