com.holonplatform.core.property

## Interface Property<T>

- All Superinterfaces:
    ConverterExpression<T>, Expression, HasConfiguration<PropertyConfiguration>, Localizable, Serializable, TypedExpression<T>, Validator.Validatable<T>
  All Known Subinterfaces:
    BeanProperty<T>, BeanProperty.Builder<T>, BooleanBeanProperty, BooleanProperty, BooleanProperty.BooleanPropertyBuilder, CloneableProperty<T,P,B>, CloneableProperty.CloneablePathProperty<T,P>, CollectionPathProperty<E,C>, CollectionProperty<E,C>, CollectionProperty.ListProperty<T>, CollectionProperty.SetProperty<T>, ListPathProperty<T>, ListPathProperty.ListPathPropertyBuilder<T>, ListVirtualProperty<T>, ListVirtualProperty.ListVirtualPropertyBuilder<T>, NumericBeanProperty<N>, NumericProperty<N>, NumericProperty.NumericPropertyBuilder<N>, PathProperty<T>, PathProperty.PathPropertyBuilder<T>, PropertyBoxProperty, PropertyBoxProperty.PropertyBoxPropertyBuilder, QueryFunction.Avg, QueryFunction.Count, QueryFunction.Max<T>, QueryFunction.Min<T>, QueryFunction.PropertyQueryFunction<T,A>, QueryFunction.Sum<T>, SetPathProperty<T>, SetPathProperty.SetPathPropertyBuilder<T>, SetVirtualProperty<T>, SetVirtualProperty.SetVirtualPropertyBuilder<T>, StringBeanProperty, StringFunction, StringFunction.Lower, StringFunction.Upper, StringProperty, StringProperty.StringPropertyBuilder, TemporalBeanProperty<T>, TemporalFunction.Day, TemporalFunction.Hour, TemporalFunction.Month, TemporalFunction.Year, TemporalProperty<T>, TemporalProperty.TemporalPropertyBuilder<T>, VirtualProperty<T>, VirtualProperty.Builder<T,P,B>, VirtualProperty.VirtualPropertyBuilder<T>

      public interface Property<T>
      extends Validator.Validatable<T>, Localizable, HasConfiguration<PropertyConfiguration>, ConverterExpression<T>, 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.

  A property can be identified by a symbolic name, which can be obtained through the `getName()` method.

  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.

  The property `equals` and `hashCode` logic can be customized using suitable `EqualsHandler` and `HashCodeProvider` functions. See `Property.Builder.equalsHandler(EqualsHandler)` and `Property.Builder.hashCodeProvider(HashCodeProvider)` methods for further details.

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

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `Property.Builder<T,P extends Property<T>,B extends Property.Builder<T,P,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`

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

      `Expression.ExpressionResolverFunction<E extends Expression,R extends Expression>, Expression.InvalidExpressionException`

  - ### 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.
    `default Optional<ExpressionValueConverter<T,?>>` | `getExpressionValueConverter()` Get the expression value type converter, if available.
    `String` | `getName()` Get the name which identifies this property.
    `default Optional<TemporalType>` | `getTemporalType()` If the expression type represents a temporal type, get the actual `TemporalType` of the type.
    `Class<? extends T>` | `getType()` Get the 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, of, of`

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

      `hasConfiguration`

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

      `getModelType, getModelValue`

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

      `isCollectionExpression, isConverterExpression`

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

      `validate`

- - ### Method Detail

    - #### getName

          String getName()

      Get the name which identifies this property.
      Returns:
        The property name (should be not null)

    - #### getType

          Class<? extends T> getType()

      Get the type of values supported by this property.
      Specified by:
        `getType` in interface `TypedExpression<T>`
      Returns:
        Property value type (not null)

    - #### 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: it only provides methods to read configuration parameters. The configuration parameters setting is done at property creation time, using the `Property.Builder.configuration(String, Object)` and `Property.Builder.configuration(ConfigProperty, Object)` methods provided by Property `Property.Builder`.

      Specified by:
        `getConfiguration` in interface `HasConfiguration<PropertyConfiguration>`
      Returns:
        The `PropertyConfiguration` of this property (immutable and not null)

    - #### getTemporalType

          default Optional<TemporalType> getTemporalType()

      Description copied from interface: `TypedExpression`
      If the expression type represents a temporal type, get the actual `TemporalType` of the type.
      Specified by:
        `getTemporalType` in interface `TypedExpression<T>`
      Returns:
        Optional temporal type

    - #### 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`

    - #### getExpressionValueConverter

          default Optional<ExpressionValueConverter<T,?>> getExpressionValueConverter()

      Description copied from interface: `ConverterExpression`
      Get the expression value type converter, if available.
      Specified by:
        `getExpressionValueConverter` in interface `ConverterExpression<T>`
      Returns:
        Optional `ExpressionValueConverter`

    - #### 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 © 2019 The Holon Platform. All rights reserved.