com.holonplatform.core.beans

## Interface BeanIntrospector

-     public interface BeanIntrospector

  Provides functionalities to introspect Java Beans and obtain informations about bean properties, methods and configuration.
  Since:
    5.0.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `BeanIntrospector.BeanIntrospectionException` Exception thrown for bean introspection failures.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CONTEXT_KEY` Default `Context` resource key

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addBeanPropertyPostProcessor(BeanPropertyPostProcessor beanPropertyPostProcessor)` Adds a `BeanPropertyPostProcessor` to handle `BeanProperty` configuration during introspection.
    `void` | `addBeanPropertySetPostProcessor(BeanPropertySetPostProcessor beanPropertySetPostProcessor)` Adds a `BeanPropertySetPostProcessor` to setup `BeanPropertySet` configuration during introspection.
    `boolean` | `clearCache()` If caching is enabled and supported, clear current introspection cache.
    `static BeanIntrospector` | `get()` Gets the current `BeanIntrospector` instance.
    `static BeanIntrospector` | `getDefault()` Return the default `BeanIntrospector` using default `ClassLoader`.
    `static BeanIntrospector` | `getDefault(ClassLoader classLoader)` Return the default `BeanIntrospector` using given `classLoader`.
    `<T> BeanPropertySet<T>` | `getPropertySet(Class<? extends T> beanClass)` Introspect given Java Bean `beanClass` and provides a `BeanPropertySet` to learn about bean properties and configuration.
    `<T> BeanPropertySet<T>` | `getPropertySet(Class<? extends T> beanClass, Path<?> parentPath)` Deprecated. The root bean property path will always be a `Path.FinalPath` typed on bean class and with the bean class name as path name. Use `getPropertySet(Class)` instead.
    `default <T> PropertyBox` | `read(PropertyBox propertyBox, T instance)` Read the property values from given bean instance into the given `PropertyBox`, using given `propertyBox` property set.
    `<T> PropertyBox` | `read(PropertyBox propertyBox, T instance, boolean ignoreMissing)` Read the property values from given bean instance into the given `PropertyBox`, using given `propertyBox` property set.
    `<T> PropertyBox` | `read(T instance)` Read the property values from given bean instance into a `PropertyBox`, using the Bean property set as the `propertyBox` property set.
    `void` | `removeBeanPropertyPostProcessor(BeanPropertyPostProcessor beanPropertyPostProcessor)` Removes a `BeanPropertyPostProcessor`.
    `void` | `removeBeanPropertySetPostProcessor(BeanPropertySetPostProcessor beanPropertySetPostProcessor)` Removes a `BeanPropertySetPostProcessor`.
    `default <T> T` | `write(PropertyBox propertyBox, T instance)` Write the property values contained into given `PropertyBox` into given bean instance.
    `<T> T` | `write(PropertyBox propertyBox, T instance, boolean ignoreMissing)` Write the property values contained into given `PropertyBox` into given bean instance.

- - ### Field Detail

    - #### CONTEXT_KEY

          static final String CONTEXT_KEY

      Default `Context` resource key

  - ### Method Detail

    - #### getPropertySet

          <T> BeanPropertySet<T> getPropertySet(Class<? extends T> beanClass)

      Introspect given Java Bean `beanClass` and provides a `BeanPropertySet` to learn about bean properties and configuration.

      The root bean property path will always be a `Path.FinalPath` typed on bean class and with the bean class name as path name.

      Type Parameters:
        `T` - Bean class type
      Parameters:
        `beanClass` - Bean class to introspect (not null)
      Returns:
        A `BeanPropertySet` describing the target bean properties and configuration
      Throws:
        `BeanIntrospector.BeanIntrospectionException` - If an exception occurs during introspection

    - #### getPropertySet

          @Deprecated
          <T> BeanPropertySet<T> getPropertySet(Class<? extends T> beanClass,
                                                             Path<?> parentPath)

      Deprecated. The root bean property path will always be a `Path.FinalPath` typed on bean class and with the bean class name as path name. Use `getPropertySet(Class)` instead.
      Introspect given Java Bean `beanClass` and provides a `BeanPropertySet` to learn about bean properties and configuration. If a `parentPath` is specified, it will be setted as bean root properties parent path.
      Type Parameters:
        `T` - Bean class type
      Parameters:
        `beanClass` - Bean class to introspect (not null)
        `parentPath` - Optional parent path to set as bean root properties parent path
      Returns:
        A `BeanPropertySet` describing the target bean properties and configuration
      Throws:
        `BeanIntrospector.BeanIntrospectionException` - If an exception occurs during introspection

    - #### read

          <T> PropertyBox read(PropertyBox propertyBox,
                               T instance,
                               boolean ignoreMissing)

      Read the property values from given bean instance into the given `PropertyBox`, using given `propertyBox` property set.

      The matching between the PropertyBox properties and the bean properties is performed by property name, so only the PropertyBox properties which implements `Path` will be taken into account, using `Path.getName()` as property name.

      Any `PropertyValueConverter` will be applied to read values from bean data model.

      Type Parameters:
        `T` - Bean type
      Parameters:
        `ignoreMissing` - `true` to ignore properties of the PropertyBox property set which are not present as bean property. If `false`, when a property of the PropertyBox property set does not match with any of the bean properties, a `Property.PropertyNotFoundException` is thrown.
        `propertyBox` - PropertyBox into which to write the property values (not null)
        `instance` - Bean instance from which read the property values (not null)
      Returns:
        The updated PropertyBox
      Throws:
        `Property.PropertyNotFoundException` - If `ignoreMissing` is `false` and a property of the PropertyBox property set does not match with any of the bean properties
        `Property.PropertyAccessException` - Error accessing bean properties
        `TypeMismatchException` - If the bean property type and the PropertyBox property type mismatch for a property
        `Validator.ValidationException` - If not `PropertyBox.isInvalidAllowed()` for given property box and one of the property values validation failed

    - #### read

          default <T> PropertyBox read(PropertyBox propertyBox,
                                       T instance)

      Read the property values from given bean instance into the given `PropertyBox`, using given `propertyBox` property set.

      The matching between the PropertyBox properties and the bean properties is performed by property name, so only the PropertyBox properties which implements `Path` will be taken into account, using `Path.getName()` as property name.

      Any `PropertyValueConverter` will be applied to read values from bean data model.

      Type Parameters:
        `T` - Bean type
      Parameters:
        `propertyBox` - PropertyBox into which to write the property values (not null)
        `instance` - Bean instance from which to read the property values (not null)
      Returns:
        The updated PropertyBox
      Throws:
        `Property.PropertyNotFoundException` - If a property of the PropertyBox property set does not match with any of the bean properties
        `Property.PropertyAccessException` - Error accessing bean properties
        `TypeMismatchException` - If the bean property type and the PropertyBox property type mismatch for a property
        `Validator.ValidationException` - If not `PropertyBox.isInvalidAllowed()` for given property box and one of the property values validation failed

    - #### read

          <T> PropertyBox read(T instance)

      Read the property values from given bean instance into a `PropertyBox`, using the Bean property set as the `propertyBox` property set.

      By default, no property value validation is performed. Use `PropertyBox.validate()` to validate the property values or use the `read(PropertyBox, Object)` for finer control on the `PropertyBox` instance to use.

      Type Parameters:
        `T` - Bean type
      Parameters:
        `instance` - Bean instance from which to read the property values (not null)
      Returns:
        A `PropertyBox` with the Bean class property set and with the property values read from the Bean instance
      Throws:
        `Property.PropertyAccessException` - Error accessing bean properties

    - #### write

          <T> T write(PropertyBox propertyBox,
                      T instance,
                      boolean ignoreMissing)

      Write the property values contained into given `PropertyBox` into given bean instance.

      The matching between the PropertyBox properties and the bean properties is performed by property name, so only the PropertyBox properties which implements `Path` will be taken into account, using `Path.getName()` as property name.

      Any `PropertyValueConverter` will be applied to write values to bean data model.

      Type Parameters:
        `T` - Bean type
      Parameters:
        `ignoreMissing` - `true` to ignore properties of the PropertyBox property set which are not present as bean property. If `false`, when a property of the PropertyBox property set does not match with any of the bean properties, a `Property.PropertyNotFoundException` is thrown.
        `propertyBox` - PropertyBox from which read the property values (not null)
        `instance` - Bean instance to which to write the property values (not null)
      Returns:
        The updated bean instance
      Throws:
        `Property.PropertyNotFoundException` - If `ignoreMissing` is `false` and a property of the PropertyBox property set does not match with any of the bean properties
        `Property.PropertyAccessException` - Error accessing bean properties
        `TypeMismatchException` - If the bean property type and the PropertyBox property type mismatch for a property

    - #### write

          default <T> T write(PropertyBox propertyBox,
                              T instance)

      Write the property values contained into given `PropertyBox` into given bean instance.

      The matching between the PropertyBox properties and the bean properties is performed by property name, so only the PropertyBox properties which implements `Path` will be taken into account, using `Path.getName()` as property name.

      Any `PropertyValueConverter` will be applied to write values to bean data model.

      Type Parameters:
        `T` - Bean type
      Parameters:
        `propertyBox` - PropertyBox from which read the property values (not null)
        `instance` - Bean instance to which to write the property values (not null)
      Returns:
        The updated bean instance
      Throws:
        `Property.PropertyNotFoundException` - If a property of the PropertyBox property set does not match with any of the bean properties
        `Property.PropertyAccessException` - Error accessing bean properties
        `TypeMismatchException` - If the bean property type and the PropertyBox property type mismatch for a property

    - #### addBeanPropertySetPostProcessor

          void addBeanPropertySetPostProcessor(BeanPropertySetPostProcessor beanPropertySetPostProcessor)

      Adds a `BeanPropertySetPostProcessor` to setup `BeanPropertySet` configuration during introspection.
      Parameters:
        `beanPropertySetPostProcessor` - BeanPropertySetPostProcessor to add (not null)

    - #### removeBeanPropertySetPostProcessor

          void removeBeanPropertySetPostProcessor(BeanPropertySetPostProcessor beanPropertySetPostProcessor)

      Removes a `BeanPropertySetPostProcessor`.
      Parameters:
        `beanPropertySetPostProcessor` - BeanPropertySetPostProcessor to remove (not null)

    - #### addBeanPropertyPostProcessor

          void addBeanPropertyPostProcessor(BeanPropertyPostProcessor beanPropertyPostProcessor)

      Adds a `BeanPropertyPostProcessor` to handle `BeanProperty` configuration during introspection.
      Parameters:
        `beanPropertyPostProcessor` - BeanPropertyPostProcessor to add (not null)

    - #### removeBeanPropertyPostProcessor

          void removeBeanPropertyPostProcessor(BeanPropertyPostProcessor beanPropertyPostProcessor)

      Removes a `BeanPropertyPostProcessor`.
      Parameters:
        `beanPropertyPostProcessor` - BeanPropertyPostProcessor to remove (not null)

    - #### clearCache

          boolean clearCache()

      If caching is enabled and supported, clear current introspection cache.
      Returns:
        `true` if caching is supported and was cleared

    - #### get

          static BeanIntrospector get()

      Gets the current `BeanIntrospector` instance.
      Returns:
        The `Context`-bound BeanIntrospector instance, if available using `CONTEXT_KEY` as context key, or the default instance for the default ClassLoader obtained through `getDefault()`.

    - #### getDefault

          static BeanIntrospector getDefault(ClassLoader classLoader)

      Return the default `BeanIntrospector` using given `classLoader`.

      The default introspector is inited loading `BeanPropertyPostProcessor`s using fully qualified name of its implementation class name to a `com.holonplatform.core.beans.BeanPropertyPostProcessor` file in the `META-INF/services` directory.

      Parameters:
        `classLoader` - ClassLoader to use
      Returns:
        Default BeanIntrospector

    - #### getDefault

          static BeanIntrospector getDefault()

      Return the default `BeanIntrospector` using default `ClassLoader`.

      The default introspector is inited loading `BeanPropertyPostProcessor`s using fully qualified name of its implementation class name to a `com.holonplatform.core.beans.BeanPropertyPostProcessor` file in the `META-INF/services` directory.

      Returns:
        Default BeanIntrospector

Copyright © 2019 The Holon Platform. All rights reserved.