Package com.norconex.commons.lang.bean

# Class BeanUtil

java.lang.Object
com.norconex.commons.lang.bean.BeanUtil

public final class BeanUtil extends Object

Bean/object utilities.

Since:
  2.0.0
See Also:
  - `FluentPropertyDescriptor`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <T> T`
  `clone(T bean)`
  Clones the given object by creating a new instance of the same type and performing shallow copies of the given object property values over the corresponding target properties of the new object.
  `static <T> void`
  `copyProperties(T target, T source)`
  Performs shallow copies of source object property values over the corresponding target properties.
  `static <T> void`
  `copyPropertiesOverNulls(T target, T source)`
  Performs shallow copies of source object property values over the corresponding target properties whose values are `null`.
  `static <T> String`
  `diff(T bean1, T bean2)`
  Checks for differences between two beans and returns different property values as a formatted string.
  `static <T> List<T>`
  `find(Object bean, @NonNull Class<T> type)`
  Finds a list of objects matching the given type by traversing the supplied object graph (i.e., itself and its child objects, recursively).
  `static List<Object>`
  `getChildren(Object bean)`
  Gets child property beans of the supplied objects (nested beans).
  `static List<FluentPropertyDescriptor>`
  `getPropertyDescriptors(Class<?> beanClass)`
  Gets a list of fluent property descriptors from the supplied bean class.
  `static List<FluentPropertyDescriptor>`
  `getPropertyDescriptors(Object bean)`
  Gets a list of fluent property descriptors from the supplied bean.
  `static Class<?>`
  `getPropertyGenericType(Class<?> beanClass, String propertyName)`
  Gets the generic type of a class property.
  `static Class<?>`
  `getPropertyType(Object bean, String propertyName)`
  Gets the type of specified object property based on its property descriptor.
  `static Method`
  `getReadMethod(Class<?> beanClass, String propertyName)`
  Gets the read method (getter) for a bean property.
  `static Method`
  `getReadMethod(Object bean, String propertyName)`
  Gets the read method (getter) for a bean property.
  `static <T> T`
  `getValue(Object bean, PropertyDescriptor propertyDescriptor)`
  Gets the value of a bean property based on a `PropertyDescriptor`.
  `static <T> T`
  `getValue(Object bean, String propertyName)`
  Gets the value of a bean property.
  `static Method`
  `getWriteMethod(Class<?> beanClass, String propertyName)`
  Gets the write method (setter) for a bean property.
  `static Method`
  `getWriteMethod(Class<?> beanClass, String propertyName, Class<?> propertyType)`
  Gets the write method (setter) for a bean property.
  `static Method`
  `getWriteMethod(Object bean, String propertyName)`
  Gets the write method (setter) for a bean property.
  `static boolean`
  `hasChildren(Object bean)`
  Gets whether the supplied object has any children (nested beans).
  `static boolean`
  `isGettable(Object bean, String propertyName)`
  Deprecated.
  Use `isReadable(Object, String)` instead
  `static boolean`
  `isReadable(Class<?> beanClass, String propertyName)`
  Gets whether a given class property has a read method for it (getter).
  `static boolean`
  `isReadable(Object bean, String propertyName)`
  Gets whether a given bean property has a read method for it (getter).
  `static boolean`
  `isSettable(Object bean, String propertyName)`
  Deprecated.
  Use `isWritable(Object, String)` instead.
  `static boolean`
  `isWritable(Class<?> beanClass, String propertyName)`
  Gets whether a given bean property has a write method for it (setter).
  `static boolean`
  `isWritable(Object bean, String propertyName)`
  Gets whether a given bean property has a write method for it (setter).
  `static void`
  `setValue(@NonNull Object bean, @NonNull String propertyName, Object value)`
  Sets the value of a bean property only if it is writable.
  `static Map<String,Object>`
  `toMap(Object bean)`
  Converts a bean to a map where the keys are the object property names and values are the object property values.
  `static Properties`
  `toProperties(Object bean, String... ignoredProperties)`
  Converts a bean to a `Properties` instance where the keys are the object property names and values are the object property values, converted to string, with support for arrays and collections.
  `static boolean`
  `visit(Object bean, Predicate<Object> visitor)`
  Visits objects by traversing the supplied object graph (i.e., itself and its child objects, recursively) for as long as the predicate returns `true`.
  `static <T> boolean`
  `visit(Object bean, Predicate<T> visitor, Class<T> type)`
  Visits objects matching the given type by traversing the supplied object graph (i.e., itself and its child objects, recursively) for as long as the predicate returns `true`.
  `static void`
  `visitAll(Object bean, Consumer<Object> visitor)`
  Visits all objects by traversing the supplied object graph (i.e., itself and its child objects, recursively).
  `static <T> void`
  `visitAll(Object bean, Consumer<T> visitor, Class<T> type)`
  Visits all objects matching the given type by traversing the supplied object graph (i.e., itself and its child objects, recursively).
  `static void`
  `visitAllProperties(Object bean, BiConsumer<Object,PropertyDescriptor> visitor)`
  Visits all properties of the supplied object by traversing its object graph (i.e., the supplied object properties and its child object properties, recursively).
  `static <T> void`
  `visitAllProperties(Object bean, BiConsumer<T,PropertyDescriptor> visitor, Class<T> type)`
  Visits all properties of objects matching the given type starting with the supplied object, traversing its object graph (i.e., the supplied object properties and its child object properties, recursively).
  `static boolean`
  `visitProperties(Object bean, BiPredicate<Object,PropertyDescriptor> visitor)`
  Visits all properties of the supplied object by traversing its object graph (i.e., the supplied object properties and its child object properties, recursively) for as long as the predicate returns `true`.
  `static <T> boolean`
  `visitProperties(Object bean, BiPredicate<Object,PropertyDescriptor> visitor, Class<T> type)`
  Visits all properties of objects matching the given type starting with the supplied object, traversing its object graph (i.e., the supplied object properties and its child object properties, recursively) for as long as the predicate returns `true`.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### getPropertyDescriptors

    public static List<FluentPropertyDescriptor> getPropertyDescriptors(Object bean)

    Gets a list of fluent property descriptors from the supplied bean. Only beans and properties meeting these conditions will have their property descriptors extracted:

    - Bean class must have a public, no-argument constructor
    - Property field must be private
    - Property must have at least one public read or write method.

    If there is an error in retrieving a properties, it will be silently skipped.

    Contrary to regular Java beans, the supplied class does not have to implement `Serializable`.

    Since 3.0.0, properties descriptors with read-only or write-only methods are supported and method name variations will be used to detect read and write methods.

    Parameters:
      `bean` - the bean to get property descriptors from
    Returns:
      list of property descriptors or an empty list if the supplied bean does not qualify or is `null`.
    See Also:
      - `FluentPropertyDescriptor`

  - ### getPropertyDescriptors

    public static List<FluentPropertyDescriptor> getPropertyDescriptors(Class<?> beanClass)

    Gets a list of fluent property descriptors from the supplied bean class. Only classes and properties meeting these conditions will have their property descriptors extracted:

    - Bean class must have a public, no-argument constructor
    - Property field must be private
    - Property must have at least one public read or write method.

    If there is an error in retrieving a properties, it will be silently skipped.

    Contrary to regular Java beans, the supplied class does not have to implement `Serializable`.

    Supports method name variations for accessors.

    Parameters:
      `beanClass` - the bean class to get property descriptors from
    Returns:
      list of property descriptors or an empty list if the supplied bean does not qualify or is `null`.
    Since:
      3.0.0
    See Also:
      - `FluentPropertyDescriptor`

  - ### copyPropertiesOverNulls

    public static <T> void copyPropertiesOverNulls(T target, T source)
    Performs shallow copies of source object property values over the corresponding target properties whose values are `null`. Supports method name variations for accessors.
    Type Parameters:
      `T` - the type of source and target objects
    Parameters:
      `target` - the target object
      `source` - the source object
    See Also:
      - `FluentPropertyDescriptor`

  - ### copyProperties

    public static <T> void copyProperties(T target, T source)
    Performs shallow copies of source object property values over the corresponding target properties. Supports method name variations for accessors.
    Type Parameters:
      `T` - the type of source and target objects
    Parameters:
      `target` - the target object
      `source` - the source object
    See Also:
      - `FluentPropertyDescriptor`

  - ### clone

    public static <T> T clone(T bean)
    Clones the given object by creating a new instance of the same type and performing shallow copies of the given object property values over the corresponding target properties of the new object. The object type must have an empty constructor. Supports method name variations for accessors.
    Type Parameters:
      `T` - the type of the object being cloned
    Parameters:
      `bean` - the object being cloned
    Returns:
      the cloned object
    Throws:
      `BeanException` - error cloning the bean
    See Also:
      - `FluentPropertyDescriptor`

  - ### diff

    public static <T> String diff(T bean1, T bean2)
    Checks for differences between two beans and returns different property values as a formatted string.
    Type Parameters:
      `T` - the type of the objects being checked for differences
    Parameters:
      `bean1` - the first object
      `bean2` - the second object
    Returns:
      a formatted string highlighting any differences

  - ### getChildren

    public static List<Object> getChildren(Object bean)
    Gets child property beans of the supplied objects (nested beans). For a bean object to be returned as a child, it needs to be accessible via a read method (getter).
    Parameters:
      `bean` - the object to obtain child beans from
    Returns:
      list of child beans

  - ### hasChildren

    public static boolean hasChildren(Object bean)
    Gets whether the supplied object has any children (nested beans). That is, it has at least one property with a read method.
    Parameters:
      `bean` - the bean to test for children
    Returns:
      `true` if the object has child beans

  - ### getPropertyType

    public static Class<?> getPropertyType(Object bean, String propertyName)
    Gets the type of specified object property based on its property descriptor. Supports method name variations for accessors.
    Parameters:
      `bean` - the object
      `propertyName` - the property name
    Returns:
      object property type or `null` if not a bean property (e.g., has no read or write method)
    Throws:
      `BeanException` - on error obtaining the property type
    See Also:
      - `FluentPropertyDescriptor`

  - ### getPropertyGenericType

    public static Class<?> getPropertyGenericType(Class<?> beanClass, String propertyName)
    Gets the generic type of a class property. Useful with collections or others classes holding a single single parameterized type.
    Parameters:
      `beanClass` - the object class
      `propertyName` - the property name
    Returns:
      object property generic type
    Throws:
      `BeanException` - on error obtaining the property generic type

  - ### getReadMethod

    public static Method getReadMethod(Object bean, String propertyName)
    Gets the read method (getter) for a bean property. Supports method name variations for accessors.
    Parameters:
      `bean` - bean object
      `propertyName` - property name
    Returns:
      read method, or `ObjectUtils.Null` if property is write-only
    Since:
      3.0.0
    See Also:
      - `FluentPropertyDescriptor`

  - ### getReadMethod

    public static Method getReadMethod(Class<?> beanClass, String propertyName)
    Gets the read method (getter) for a bean property. Supports method name variations for accessors.
    Parameters:
      `beanClass` - object class
      `propertyName` - property name
    Returns:
      read method, or `ObjectUtils.Null` if property is write-only
    Since:
      3.0.0
    See Also:
      - `FluentPropertyDescriptor`
      - `FluentPropertyDescriptor`

  - ### getWriteMethod

    public static Method getWriteMethod(Object bean, String propertyName)
    Gets the write method (setter) for a bean property. Supports method name variations for accessors.
    Parameters:
      `bean` - object
      `propertyName` - property name
    Returns:
      write method, or `null` if property is read-only
    Since:
      3.0.0
    See Also:
      - `FluentPropertyDescriptor`

  - ### getWriteMethod

    public static Method getWriteMethod(Class<?> beanClass, String propertyName)
    Gets the write method (setter) for a bean property. Supports method name variations for accessors.
    Parameters:
      `beanClass` - object class
      `propertyName` - property name
    Returns:
      write method, or `ObjectUtils.Null` if property is read-only
    Since:
      3.0.0
    See Also:
      - `FluentPropertyDescriptor`

  - ### getWriteMethod

    public static Method getWriteMethod(Class<?> beanClass, String propertyName, Class<?> propertyType)
    Gets the write method (setter) for a bean property. Supports method name variations for accessors.
    Parameters:
      `beanClass` - object class
      `propertyName` - property name
      `propertyType` - property type, or `null` if to be detected
    Returns:
      write method, or `ObjectUtils.Null` if property is read-only
    Since:
      3.0.0
    See Also:
      - `FluentPropertyDescriptor`

  - ### getValue

    public static <T> T getValue(Object bean, String propertyName)
    Gets the value of a bean property. Returns `null` if the property has no read method. Supports method name variations for accessors.
    Type Parameters:
      `T` - return value type
    Parameters:
      `bean` - the object
      `propertyName` - the property name
    Returns:
      object property value or `null` if no read method
    Throws:
      `BeanException` - on error obtaining the property value
    See Also:
      - `isReadable(Object, String)`
      - `FluentPropertyDescriptor`

  - ### getValue

    public static <T> T getValue(Object bean, PropertyDescriptor propertyDescriptor)
    Gets the value of a bean property based on a `PropertyDescriptor`. This is a convenience method equivalent to invoking the method obtained with `PropertyDescriptor.getReadMethod()` when not read-only.
    Type Parameters:
      `T` - return value type
    Parameters:
      `bean` - the object
      `propertyDescriptor` - the property descriptor
    Returns:
      object property value
    Throws:
      `BeanException` - on error obtaining the property value

  - ### isReadable

    public static boolean isReadable(Object bean, String propertyName)
    Gets whether a given bean property has a read method for it (getter). Supports method name variations for accessors.
    Parameters:
      `bean` - the object
      `propertyName` - the property name
    Returns:
      `true` if the object property as a getter method
    Throws:
      `BeanException` - on error obtaining property information
    Since:
      3.0.0, replaces now deprecated `isGettable(Object, String)`
    See Also:
      - `FluentPropertyDescriptor`

  - ### isReadable

    public static boolean isReadable(Class<?> beanClass, String propertyName)
    Gets whether a given class property has a read method for it (getter). Supports method name variations for accessors.
    Parameters:
      `beanClass` - a bean class
      `propertyName` - the property name
    Returns:
      `true` if the object property as a getter method
    Throws:
      `BeanException` - on error obtaining property information
    Since:
      3.0.0
    See Also:
      - `FluentPropertyDescriptor`

  - ### isGettable

    @Deprecated(since="3.0.0") public static boolean isGettable(Object bean, String propertyName)
    Deprecated.
    Use `isReadable(Object, String)` instead
    Gets whether a given bean property has a getter method for it.
    Parameters:
      `bean` - the object
      `propertyName` - the property name
    Returns:
      `true` if the object property as a getter method
    Throws:
      `BeanException` - on error obtaining property information

  - ### setValue

    public static void setValue(@NonNull @NonNull Object bean, @NonNull @NonNull String propertyName, Object value)
    Sets the value of a bean property only if it is writable. Otherwise does nothing. Supports method name variations for accessors.
    Parameters:
      `bean` - the object
      `propertyName` - the property name
      `value` - object property value
    Throws:
      `BeanException` - on error obtaining the property value
    See Also:
      - `isWritable(Object, String)`
      - `FluentPropertyDescriptor`

  - ### isSettable

    @Deprecated(since="3.0.0") public static boolean isSettable(Object bean, String propertyName)
    Deprecated.
    Use `isWritable(Object, String)` instead.
    Gets whether a given bean property has a write method for it (setter). Supports method name variations for accessors.
    Parameters:
      `bean` - the object
      `propertyName` - the property name
    Returns:
      `true` if the object property as a setter method
    Throws:
      `BeanException` - on error obtaining property information
    See Also:
      - `FluentPropertyDescriptor`

  - ### isWritable

    public static boolean isWritable(Object bean, String propertyName)
    Gets whether a given bean property has a write method for it (setter). Supports method name variations for accessors.
    Parameters:
      `bean` - the object
      `propertyName` - the property name
    Returns:
      `true` if the object property as a write method
    Throws:
      `BeanException` - on error obtaining property information
    Since:
      3.0.0
    See Also:
      - `FluentPropertyDescriptor`

  - ### isWritable

    public static boolean isWritable(Class<?> beanClass, String propertyName)
    Gets whether a given bean property has a write method for it (setter). Supports method name variations for accessors.
    Parameters:
      `beanClass` - bean class
      `propertyName` - property name
    Returns:
      `true` if the object property as a write method
    Throws:
      `BeanException` - on error obtaining property information
    Since:
      3.0.0
    See Also:
      - `FluentPropertyDescriptor`

  - ### toMap

    public static Map<String,Object> toMap(Object bean)
    Converts a bean to a map where the keys are the object property names and values are the object property values.
    Parameters:
      `bean` - the object to convert to a map.
    Returns:
      the converted a map
    Throws:
      `BeanException` - on error converting bean to map

  - ### toProperties

    public static Properties toProperties(Object bean, String... ignoredProperties)
    Converts a bean to a `Properties` instance where the keys are the object property names and values are the object property values, converted to string, with support for arrays and collections.
    Parameters:
      `bean` - the object to convert to properties.
      `ignoredProperties` - properties to skip (not converted)
    Returns:
      the converted properties
    Throws:
      `BeanException` - on error converting bean to properties

  - ### find

    public static <T> List<T> find(Object bean, @NonNull @NonNull Class<T> type)
    Finds a list of objects matching the given type by traversing the supplied object graph (i.e., itself and its child objects, recursively).
    Type Parameters:
      `T` - the type of objects to find
    Parameters:
      `bean` - the bean on which to find matches
      `type` - class instance of the type to find (must not be `null`)
    Returns:
      a list of objects matching the supplied type

  - ### visitAll

    public static void visitAll(Object bean, Consumer<Object> visitor)
    Visits all objects by traversing the supplied object graph (i.e., itself and its child objects, recursively).
    Parameters:
      `bean` - the bean to visit
      `visitor` - a consumer invoked for all objects visited

  - ### visitAll

    public static <T> void visitAll(Object bean, Consumer<T> visitor, Class<T> type)
    Visits all objects matching the given type by traversing the supplied object graph (i.e., itself and its child objects, recursively).
    Type Parameters:
      `T` - the type of objects to visit
    Parameters:
      `bean` - the bean to visit
      `visitor` - a consumer invoked for all objects visited
      `type` - class instance of the type to find

  - ### visit

    public static boolean visit(Object bean, Predicate<Object> visitor)
    Visits objects by traversing the supplied object graph (i.e., itself and its child objects, recursively) for as long as the predicate returns `true`. The visiting stops the moment a `false` value is returned.
    Parameters:
      `bean` - the bean to visit
      `visitor` - a predicate invoked for all objects visited
    Returns:
      `true` if the visit was complete (all predicate invocations returned `true`).

  - ### visit

    public static <T> boolean visit(Object bean, Predicate<T> visitor, Class<T> type)
    Visits objects matching the given type by traversing the supplied object graph (i.e., itself and its child objects, recursively) for as long as the predicate returns `true`. The visiting stops the moment a `false` value is returned.
    Type Parameters:
      `T` - the type of objects to visit
    Parameters:
      `bean` - the bean to visit
      `visitor` - a predicate invoked for all objects visited
      `type` - class instance of the type to find
    Returns:
      `true` if the visit was complete (all predicate invocations returned `true`).

  - ### visitAllProperties

    public static void visitAllProperties(Object bean, BiConsumer<Object,PropertyDescriptor> visitor)
    Visits all properties of the supplied object by traversing its object graph (i.e., the supplied object properties and its child object properties, recursively). For each properties, the supplied visitor takes both the property descriptor and the object instance on which the property was found.
    Parameters:
      `bean` - the bean on which visit properties
      `visitor` - a consumer invoked for all properties visited

  - ### visitAllProperties

    public static <T> void visitAllProperties(Object bean, BiConsumer<T,PropertyDescriptor> visitor, Class<T> type)
    Visits all properties of objects matching the given type starting with the supplied object, traversing its object graph (i.e., the supplied object properties and its child object properties, recursively). For each properties, the supplied visitor takes both the property descriptor and the object instance on which the property was found.
    Type Parameters:
      `T` - the type of objects to visit
    Parameters:
      `bean` - the bean on which visit properties
      `visitor` - a consumer invoked for all properties visited
      `type` - class instance of the type to find

  - ### visitProperties

    public static boolean visitProperties(Object bean, BiPredicate<Object,PropertyDescriptor> visitor)
    Visits all properties of the supplied object by traversing its object graph (i.e., the supplied object properties and its child object properties, recursively) for as long as the predicate returns `true`. The visiting stops the moment a `false` value is returned. For each properties, the supplied visitor takes both the property descriptor and the object instance on which the property was found.
    Parameters:
      `bean` - the bean to visit
      `visitor` - a predicate invoked for all properties visited
    Returns:
      `true` if the visit was complete (all predicate invocations returned `true`).

  - ### visitProperties

    public static <T> boolean visitProperties(Object bean, BiPredicate<Object,PropertyDescriptor> visitor, Class<T> type)
    Visits all properties of objects matching the given type starting with the supplied object, traversing its object graph (i.e., the supplied object properties and its child object properties, recursively) for as long as the predicate returns `true`. The visiting stops the moment a `false` value is returned. For each properties, the supplied visitor takes both the property descriptor and the object instance on which the property was found.
    Type Parameters:
      `T` - the type of objects to visit
    Parameters:
      `bean` - the bean to visit
      `visitor` - a predicate invoked for all properties visited
      `type` - class instance of the type to find
    Returns:
      `true` if the visit was complete (all predicate invocations returned `true`).