com.holonplatform.core.property

## Interface PropertyBox

- All Superinterfaces:
    HasConfiguration<ParameterSet>, Iterable<Property>, PropertySet<Property>

      public interface PropertyBox
      extends PropertySet<Property>

  PropertyBox is the base container for `Property` values, provinding methods to get and set property values, performing value validation and conversions according to property configurations.

  The set of the properties managed by a PropertyBox is well defined through the `PropertySet` abstraction.

  If the `PropertySet` to which the `PropertyBox` is bound provides a set of identifier properties, the identifier property values are used by default to check `PropertyBox` objects equality and to provide the object hash code. The default builder allows to provide a custom equals/hashCode logic using suitable `EqualsHandler` and `HashCodeProvider` functions. See `PropertyBox.Builder.equalsHandler(EqualsHandler)` and `PropertyBox.Builder.hashCodeProvider(HashCodeProvider)` methods for further details.

  By default, property value validation is enabled, and when a property value is setted in the `PropertyBox` using `setValue(Property, Object)` any property validator is invoked, throwing a `Validator.ValidationException` if the value is not valid. Property value validation can be controlled using the `setInvalidAllowed(boolean)` method. Property value validation can always be manually triggered using the `validate()` method.

  Since:
    5.0.0
  See Also:
    `PropertySet`, `PropertySet.getIdentifiers()`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `PropertyBox.Builder` Builder to build `PropertyBox` instances.
    `static interface` | `PropertyBox.PropertyValue<T>` Represents a `Property` value.

  - ### Field Summary

    - ### Fields inherited from interface com.holonplatform.core.property.PropertySet

      `CONTEXT_KEY, PROPERTY_CONFIGURATION_ATTRIBUTE`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <P extends Property> PropertyBox.Builder` | `builder(Iterable<P> properties)` Builder to create and populate a PropertyBox.
    `static <P extends Property> PropertyBox.Builder` | `builder(P... properties)` Builder to create and populate a PropertyBox.
    `default PropertyBox` | `cloneBox()` Clone this PropertyBox, i.e. create a new PropertyBox with same property set of this box and copy all the property values from this box to the newly created box.
    `default PropertyBox` | `cloneBox(Property<?>... propertySet)` Clone this PropertyBox using given `propertySet`, i.e. create a new PropertyBox and copy all given set property values from this box to the newly created box.
    `default <P extends Property> PropertyBox` | `cloneBox(PropertySet<P> propertySet)` Clone this PropertyBox using given `propertySet`, i.e. create a new PropertyBox and copy all given set property values from this box to the newly created box.
    `<T> boolean` | `containsValue(Property<T> property)` Check if this box contains given `property` with a not `null` value.
    `static <P extends Property> PropertyBox` | `create(Iterable<P> properties)` Shorter method to create a PropertyBox with given `properties` set.
    `static <P extends Property> PropertyBox` | `create(P... properties)` Shorter method to create a PropertyBox with given `properties` set.
    `<T> T` | `getValue(Property<T> property)` Get the value for given `property`.
    `<T> Optional<T>` | `getValueIfPresent(Property<T> property)` Get the value for given `property`, if property is present in this box and has a not `null` value.
    `boolean` | `isInvalidAllowed()` Gets whether to accept invalid property values when using `setValue(Property, Object)` to set a property value, i.e. ignores any `Validator` registered for property.
    `default <T> String` | `present(Property<T> property)` Present given `property` value, obtained from this PropertyBox, as a `String`, using current `PropertyValuePresenterRegistry` if available as `Context` resource to obtain a suitable `PropertyValuePresenter`, or default presenter `PropertyValuePresenterRegistry.getDefault()` otherwise.
    `<T> Stream<PropertyBox.PropertyValue<T>>` | `propertyValues()` Get the `Stream` of all the `Property`s of the property set bound to this `PropertyBox` and their values, using the `PropertyBox.PropertyValue` representation.
    `void` | `setInvalidAllowed(boolean invalidAllowed)` Set whether to accept invalid property values when using `setValue(Property, Object)` to set a property value, i.e. to ignore any `Validator` registered for property.
    `<T> void` | `setValue(Property<T> property, T value)` Set the value of given `property`.
    `void` | `validate()` Checks the validity of the value of each property in the box against every registered property validator, if any.

    - ### Methods inherited from interface com.holonplatform.core.property.PropertySet

      `asList, builder, builder, builderOf, contains, execute, getConfiguration, getFirstIdentifier, getIdentifiers, identifiers, join, of, of, of, size, stream`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, iterator, spliterator`

    - ### Methods inherited from interface com.holonplatform.core.HasConfiguration

      `hasConfiguration`

- - ### Method Detail

    - #### containsValue

          <T> boolean containsValue(Property<T> property)

      Check if this box contains given `property` with a not `null` value.
      Type Parameters:
        `T` - Property type
      Parameters:
        `property` - Property to check (not null)
      Returns:
        `true` if box contains given property and the property value is not `null`

    - #### getValue

          <T> T getValue(Property<T> property)

      Get the value for given `property`.
      Type Parameters:
        `T` - Property and value type
      Parameters:
        `property` - Property for which obtain the value (not null)
      Returns:
        Property value, or `null` if no value is associated to given property
      Throws:
        `Property.PropertyNotFoundException` - If property is not present in the box property set
        `Property.PropertyAccessException` - If an error occurred reading the property value

    - #### getValueIfPresent

          <T> Optional<T> getValueIfPresent(Property<T> property)

      Get the value for given `property`, if property is present in this box and has a not `null` value.

      Unlike `getValue(Property)`, this method does not throw a `Property.PropertyNotFoundException` when the specified property is not part of this box property set, an empty Optional is returned instead. An empty Optional is returned also when the property is present but has no value.

      Type Parameters:
        `T` - Property and value type
      Parameters:
        `property` - Property for which obtain the value (not null)
      Returns:
        Property value, or an empty Optional if property is not present in this box or has no value
      Throws:
        `Property.PropertyAccessException` - If an error occurred reading the property value

    - #### propertyValues

          <T> Stream<PropertyBox.PropertyValue<T>> propertyValues()

      Get the `Stream` of all the `Property`s of the property set bound to this `PropertyBox` and their values, using the `PropertyBox.PropertyValue` representation.

      All the properties will be part of the stream, even the ones without a value. If a property has not a value in this `PropertyBox`, `null` will be returned by `PropertyBox.PropertyValue.getValue()`.

      Type Parameters:
        `T` - Property and value type
      Returns:
        a `PropertyBox.PropertyValue` stream with all the property values

    - #### setValue

          <T> void setValue(Property<T> property,
                            T value)

      Set the value of given `property`.
      Type Parameters:
        `T` - Property and value type
      Parameters:
        `property` - Property for which to set the value (not null)
        `value` - Value to set
      Throws:
        `Property.PropertyNotFoundException` - If property is not present in the box property set
        `Property.PropertyAccessException` - If an error occurred setting the property value
        `Property.PropertyReadOnlyException` - If the property is read-only
        `Validator.ValidationException` - If not `isInvalidAllowed()` and property is `Validator.Validatable` and validation against given value was not successful

    - #### isInvalidAllowed

          boolean isInvalidAllowed()

      Gets whether to accept invalid property values when using `setValue(Property, Object)` to set a property value, i.e. ignores any `Validator` registered for property. If invalid values are not allowed and any property `Validator` do not validate the value, a `Validator.ValidationException` is thrown by `setValue(Property, Object)`.

      Default value is `false`.

      Returns:
        `true` if accept invalid property values (ignore validators), `false` otherwise

    - #### setInvalidAllowed

          void setInvalidAllowed(boolean invalidAllowed)

      Set whether to accept invalid property values when using `setValue(Property, Object)` to set a property value, i.e. to ignore any `Validator` registered for property. If invalid values are not allowed and any property `Validator` do not validate the value, a `Validator.ValidationException` is thrown by `setValue(Property, Object)`.
      Parameters:
        `invalidAllowed` - `true` to accept invalid property values (ignore validators), `false` otherwise

    - #### validate

          void validate()
                 throws Validator.ValidationException

      Checks the validity of the value of each property in the box against every registered property validator, if any. If one or more value is not valid, an `Validator.ValidationException` is thrown.
      Throws:
        `Validator.ValidationException` - One or more property value is not valid

    - #### cloneBox

          default PropertyBox cloneBox()

      Clone this PropertyBox, i.e. create a new PropertyBox with same property set of this box and copy all the property values from this box to the newly created box.
      Returns:
        A new, cloned, PropertyBox instance

    - #### cloneBox

          default <P extends Property> PropertyBox cloneBox(PropertySet<P> propertySet)

      Clone this PropertyBox using given `propertySet`, i.e. create a new PropertyBox and copy all given set property values from this box to the newly created box.
      Type Parameters:
        `P` - Actual property type
      Parameters:
        `propertySet` - Property set of the cloned PropertyBox (not null)
      Returns:
        A new, cloned, PropertyBox instance with given property set

    - #### cloneBox

          default PropertyBox cloneBox(Property<?>... propertySet)

      Clone this PropertyBox using given `propertySet`, i.e. create a new PropertyBox and copy all given set property values from this box to the newly created box.
      Parameters:
        `propertySet` - Property set of the cloned PropertyBox (not null)
      Returns:
        A new, cloned, PropertyBox instance with given property set

    - #### present

          default <T> String present(Property<T> property)

      Present given `property` value, obtained from this PropertyBox, as a `String`, using current `PropertyValuePresenterRegistry` if available as `Context` resource to obtain a suitable `PropertyValuePresenter`, or default presenter `PropertyValuePresenterRegistry.getDefault()` otherwise.
      Type Parameters:
        `T` - Property type
      Parameters:
        `property` - Property to present
      Returns:
        String presentation of the given `value`
      Throws:
        `Property.PropertyNotFoundException` - Property is not present in box property set
        `Property.PropertyAccessException` - Failed to read property value (value type is not consistent with property type or other internal errors)

    - #### create

          static <P extends Property> PropertyBox create(Iterable<P> properties)

      Shorter method to create a PropertyBox with given `properties` set.

      If given `properties` are provided as a `PropertySet` instance, any property set configuration, such as identifier properties, is inherited by the `PropertyBox` property set.

      Type Parameters:
        `P` - Actual property type
      Parameters:
        `properties` - Set of properties of the PropertyBox to create
      Returns:
        A new `PropertyBox` builder

    - #### create

          @SafeVarargs
          static <P extends Property> PropertyBox create(P... properties)

      Shorter method to create a PropertyBox with given `properties` set.
      Type Parameters:
        `P` - Actual property type
      Parameters:
        `properties` - Set of properties of the PropertyBox to create
      Returns:
        A new `PropertyBox` builder

    - #### builder

          static <P extends Property> PropertyBox.Builder builder(Iterable<P> properties)

      Builder to create and populate a PropertyBox.

      If given `properties` are provided as a `PropertySet` instance, any property set configuration, such as identifier properties, is inherited by the `PropertyBox` property set.

      Type Parameters:
        `P` - Actual property type
      Parameters:
        `properties` - Set of properties of the PropertyBox to create
      Returns:
        A new `PropertyBox` builder

    - #### builder

          @SafeVarargs
          static <P extends Property> PropertyBox.Builder builder(P... properties)

      Builder to create and populate a PropertyBox.
      Type Parameters:
        `P` - Actual property type
      Parameters:
        `properties` - Set of properties of the PropertyBox to create
      Returns:
        A new `PropertyBox` builder

Copyright © 2019 The Holon Platform. All rights reserved.