Module org.klojang.invoke
Package org.klojang.invoke

Class BeanReader<T>

java.lang.Object
org.klojang.invoke.BeanReader<T>
Type Parameters:
T - The type of the bean
public final class BeanReader<T> extends Object
A dynamic bean reader class. This class uses method handles instead of reflection to read bean properties. However, it still uses reflection to figure out what those properties are in the first place. Therefore, if you use a BeanReader to read beans residing in a Java 9+ module, that module must be "open" to reflective access. Reflection is used only transiently. No reflection objects are cached. They are disposed of once the required information has been extracted from them.

If you prefer, you can use the BeanReaderBuilder class to configure BeanReader instances in a completely reflection-free manner. You obtain a BeanReaderBuilder via BeanReader.forClass().

Author:
Ayco Holleman

  • Constructor Details

    • BeanReader

      public BeanReader(Class<T> beanClass, String... properties)
      Creates a BeanReader for the specified properties of the specified class. You can optionally specify an array of properties that you intend to read. If you specify a zero-length array all properties will be readable. JavaBeans naming conventions will be applied regarding which methods qualify as getters.
      Parameters:
      beanClass - the bean class
      properties - the properties to be included/excluded

    • BeanReader

      public BeanReader(Class<T> beanClass, IncludeExclude includeExclude, String... properties)
      Creates a BeanReader for the specified properties of the specified class. You can optionally specify an array of properties that you intend to read. If you specify a zero-length array, all properties will be readable. JavaBeans naming conventions will be applied regarding which methods qualify as getters.
      Parameters:
      beanClass - the bean class
      includeExclude - whether to include or exclude the specified properties
      properties - the properties to be included/excluded

    • BeanReader

      public BeanReader(Class<T> beanClass, boolean strictNaming, IncludeExclude includeExclude, String... properties)
      Creates a BeanReader for the specified properties of the specified class. You can optionally specify an array of properties that you intend to read. If you specify a zero-length array, all properties will be readable. If you intend to use this BeanReader to repetitively read just one or two properties from bulky bean types, explicitly specifying the properties you intend to read might make the BeanReader slightly more efficient.

      Specifying non-existent properties will not cause an exception to be thrown. They will be tacitly ignored.

      Parameters:
      beanClass - the bean class
      strictNaming - if false, all methods with a zero-length parameter list and a non-void return type, except getClass(), hashCode() and toString(), will be regarded as getters. Otherwise JavaBeans naming conventions will be applied regarding which methods qualify as getters. By way of exception, methods returning a Boolean are allowed to have a name starting with "is" (just like methods returning a boolean). The strictNaming parameter is quietly ignored for record classes. Records are always processed as though strictNaming were false.
      includeExclude - whether to include or exclude the subsequently specified properties
      properties - the properties to be included/excluded

    • BeanReader

      public BeanReader(Class<T> beanClass, boolean strictNaming, BeanValueTransformer<T> transformer, IncludeExclude includeExclude, String... properties)
      Creates a BeanReader for the specified properties of the specified class. You can optionally specify an array of properties that you intend to read. If you specify a zero-length array, all properties will be readable. If you intend to use this BeanReader to repetitively read just one or two properties from bulky bean types, explicitly specifying the properties you intend to read might make the BeanReader slightly more efficient.

      Specifying non-existent properties will not cause an exception to be thrown. They will be tacitly ignored.

      Parameters:
      beanClass - the bean class
      strictNaming - if false, all methods with a zero-length parameter list and a non-void return type, except getClass(), hashCode() and toString(), will be regarded as getters. Otherwise JavaBeans naming conventions will be applied regarding which methods qualify as getters. By way of exception, methods returning a Boolean are allowed to have a name starting with "is" (just like methods returning a boolean). The strictNaming parameter is quietly ignored for record classes. Records are always processed as though strictNaming were false.
      transformer - a conversion function for bean values. The function is passed the bean from which the value was retrieved; the property that was read; and the value of the property. Using these three parameters, the function can compute a new value, which will be the value that is actually returned
      includeExclude - whether to include or exclude the subsequently specified properties
      properties - the properties to be included/excluded

  • Method Details

    • forClass

      public static <T> BeanReaderBuilder<T> forClass(Class<T> beanClass)
      Returns a Builder for BeanReader instances. Note that the specified type may just as well be a record or enum type.
      Type Parameters:
      T - the type of the objects to be read
      Parameters:
      beanClass - the class for which to create a BeanReader
      Returns:
      a Builder for BeanReader instances

    • read

      public <U> U read(T bean, String property) throws NoSuchPropertyException
      Returns the value of the specified property on the specified bean. If the property does not exist a NoSuchPropertyException is thrown. If this BeanReader was instantiated with a BeanValueTransformer, the output from the transformer is returned.
      Type Parameters:
      U - the type of the return value
      Parameters:
      bean - the bean instance
      property - The property
      Returns:
      its value
      Throws:
      NoSuchPropertyException - if the specified property does not exist

    • getBeanClass

      public Class<T> getBeanClass()
      Returns the class of the objects this BeanReader can read.
      Returns:
      the class of the objects BeanReader can read

    • canRead

      public boolean canRead(String property)
      Returns true if the specified string represents a property that can be read by this BeanReader. Note that this check is already done by the read method before it will actually attempt to read from the provided bean. Only perform this check if there is a considerable chance that the provided string is not a readable property.
      Parameters:
      property - The string to be tested
      Returns:
      true if the specified string represents a property that can be read by this BeanReader
      See Also:

    • getReadableProperties

      public Set<String> getReadableProperties()
      Returns the properties that this BeanReader will read. That will be all read-accessible properties minus the properties excluded through the constructor (if any).
      Returns:
      the properties that this BeanReader will read

    • getIncludedGetters

      public Map<String,Getter> getIncludedGetters()
      Returns the getters used by the BeanReader to read bean properties. The returned Map maps the name of a property to the Getter used to read it.
      Returns:
      all getters used to read bean properties.