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:

  • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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).