com.holonplatform.core.property

## Interface Property<T>

- All Superinterfaces:
    Localizable, Serializable, Validator.Validatable<T>
  All Known Subinterfaces:
    BeanProperty<T>, BeanProperty.Builder<T>, FunctionExpression.FunctionExpressionProperty<T>, FunctionExpression.PathFunctionExpressionProperty<P,T>, PathProperty<T>, PathProperty.PathPropertyBuilder<T>, VirtualProperty<T>, VirtualProperty.Builder<T,B>

      public interface Property<T>
      extends Validator.Validatable<T>, Localizable, Serializable

  Property is the base interface to represent a generic data attribute. Declares its value type through `getType()` method and it is generalized on such type.

  Supports a `PropertyValueConverter` to be used within a `PropertyBox` abstraction when property is bound to a data model, allowing property value conversion in both directions when property value type and data model value type does not match.

  A property brings with it a generic `PropertyConfiguration` structure, organized as a parameter set, which can be used to set custom configuration attributes.

  This property is `Validator.Validatable`, supporting property value `Validator`s.

  Extends `Localizable` to optionally provide a localizable message which describes the property.

  Since:
    4.4.0
  See Also:
    `PathProperty`, `VirtualProperty`, `PropertySet`, `PropertyBox`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `Property.Builder<T,B extends Property.Builder<T,B>>` Base `Property` builder.
    `static class` | `Property.PropertyAccessException` Base exception class to all `Property` related exceptions.
    `static class` | `Property.PropertyNotFoundException` Exception thrown when a property is not found in a property set.
    `static class` | `Property.PropertyReadException` Generic exception thrown for property value reading failures.
    `static class` | `Property.PropertyReadOnlyException` Exception thrown when trying to set a value for a read-only property.
    `static class` | `Property.PropertyWriteException` Generic exception thrown for property value writing failures.

    - ### Nested classes/interfaces inherited from interface com.holonplatform.core.i18n.Localizable

      `Localizable.LocalizableBuilder, Localizable.LocalizationException`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `PropertyConfiguration` | `getConfiguration()` Gets the configuration associated to this property.
    `default Object` | `getConvertedValue(T value)` Return the given `value` against this property, converting it to required model data type if a `PropertyValueConverter` is present.
    `Optional<PropertyValueConverter<T,?>>` | `getConverter()` Get the converter to perform property value conversions between property value and the corresponding data model value.
    `Class<? extends T>` | `getType()` Type of values supported by this property
    `boolean` | `isReadOnly()` Gets whether property is read-only, i.e. does not support value setting.
    `default String` | `present(T value)` Present given property `value` as a `String`, using current `PropertyValuePresenterRegistry` if available as `Context` resource or the default instance otherwise.
    `default <R> R` | `render(Class<R> renderType)` Render this property as given `renderType`.
    `default <R> Optional<R>` | `renderIfAvailable(Class<R> renderType)` Render this property as given `renderType` if a suitable `PropertyRenderer` for given rendering type is available from the `PropertyRendererRegistry` obtained from current `Context` or from the default one for current ClassLoader.

    - ### Methods inherited from interface com.holonplatform.core.Validator.Validatable

      `getValidators, validate`

    - ### Methods inherited from interface com.holonplatform.core.i18n.Localizable

      `builder, getMessage, getMessageArguments, getMessageCode`

- - ### Method Detail

    - #### getType

          Class<? extends T> getType()

      Type of values supported by this property
      Returns:
        Property value type

    - #### isReadOnly

          boolean isReadOnly()

      Gets whether property is read-only, i.e. does not support value setting.

      When a property is read-only, a `Property.PropertyReadOnlyException` should be thrown by property value setting methods.

      Returns:
        `true` if property is read-only

    - #### getConfiguration

          PropertyConfiguration getConfiguration()

      Gets the configuration associated to this property.

      This configuration is considered as immutable, and only provide methods to read configuration parameters. The configuration parameters setting is done at property creation time, using `Property.Builder.configuration(String, Object)` and `Property.Builder.configuration(ConfigProperty, Object)` methods provided by Property `Property.Builder`.

      Returns:
        The `PropertyConfiguration` of this property (immutable and not null)

    - #### getConverter

          Optional<PropertyValueConverter<T,?>> getConverter()

      Get the converter to perform property value conversions between property value and the corresponding data model value. The `PropertyValueConverter` is supported out-of-the-box when property value is handled using a `PropertyBox`.
      Returns:
        Optional converter

    - #### getConvertedValue

          default Object getConvertedValue(T value)

      Return the given `value` against this property, converting it to required model data type if a `PropertyValueConverter` is present.
      Parameters:
        `value` - Property value (can be null)
      Returns:
        Model value, possibly converted using the `PropertyValueConverter`

    - #### present

          default String present(T value)

      Present given property `value` as a `String`, using current `PropertyValuePresenterRegistry` if available as `Context` resource or the default instance otherwise. If a `PropertyValuePresenter` is not available from registry, simple `Object.toString()` representation of the value is returned.
      Parameters:
        `value` - Value to present as a String
      Returns:
        String presentation of the given `value`

    - #### render

          default <R> R render(Class<R> renderType)

      Render this property as given `renderType`.

      To successfully render the property, a suitable `PropertyRenderer` for given render type must be available from the `PropertyRendererRegistry` obtained from current `Context` or from the default one for current ClassLoader.

      Type Parameters:
        `R` - Rendered object type
      Parameters:
        `renderType` - Render type
      Returns:
        Rendered property as given render type
      Throws:
        `PropertyRendererRegistry.NoSuitableRendererAvailableException` - if no PropertyRenderer is available for this property and given rendering type

    - #### renderIfAvailable

          default <R> Optional<R> renderIfAvailable(Class<R> renderType)

      Render this property as given `renderType` if a suitable `PropertyRenderer` for given rendering type is available from the `PropertyRendererRegistry` obtained from current `Context` or from the default one for current ClassLoader.
      Type Parameters:
        `R` - Rendered object type
      Parameters:
        `renderType` - Render type
      Returns:
        Rendered property as given render type, or an empty Optional if a suitable PropertyRenderer is not available

Copyright © 2017 The Holon Platform. All rights reserved.