Package rife.tools

Class BeanUtils

java.lang.Object
rife.tools.BeanUtils
public final class BeanUtils extends Object
Utility class providing methods for working with Java beans.

Since 1.10, bean properties can use Optional getters. Their values will be unwrapped when they are read, where an empty Optional means the same as null, and the type of such a property is the Optional's value type. Since the standard JavaBeans introspector drops a plain-typed setter that sits next to an Optional getter, RIFE2 pairs them up again so that the property simply behaves like a regular read-write property. A setter that declares an Optional parameter will receive its values wrapped.

Since:
1.0

  • Method Details

    • getBeanInfo

      public static BeanInfo getBeanInfo(Class<?> beanClass) throws BeanUtilsException
      Gets the BeanInfo for the specified beanClass.

      The property descriptors describe Optional properties directly, which means that PropertyDescriptor.getPropertyType() will return the Optional's value type and that PropertyDescriptor.getWriteMethod() will return the plain-typed setter that the standard introspector dropped. This also applies to properties that only have an Optional setter.

      Parameters:
      beanClass - The Class to get the BeanInfo for.
      Returns:
      The BeanInfo for the specified beanClass.
      Throws:
      BeanUtilsException - If an error occurs while introspecting the bean.
      Since:
      1.0

    • getPropertyNames

      public static Set<String> getPropertyNames(Class beanClass, String[] includedProperties, String[] excludedProperties, String prefix) throws BeanUtilsException
      Gets the names of the properties of the specified beanClass that have both read and write accessors.
      Parameters:
      beanClass - The Class to get the property names for.
      includedProperties - The properties that should be included.
      excludedProperties - The properties that should be excluded.
      prefix - The prefix to apply to the property name.
      Returns:
      A set containing the names of the properties.
      Throws:
      BeanUtilsException - If an error occurs while introspecting the bean.
      Since:
      1.0

    • getPropertyNames

      public static Set<String> getPropertyNames(BeanUtils.Accessors accessors, Class beanClass, String[] includedProperties, String[] excludedProperties, String prefix) throws BeanUtilsException
      Gets the names of the properties of the specified beanClass that have the specified accessors.
      Parameters:
      accessors - The Accessors to use when retrieving the property names.
      beanClass - The Class to get the property names for.
      includedProperties - The properties that should be included.
      excludedProperties - The properties that should be excluded.
      prefix - The prefix to apply to the property name.
      Returns:
      A set containing the names of the properties.
      Throws:
      BeanUtilsException - If an error occurs while introspecting the bean.
      Since:
      1.0

    • processProperties

      public static void processProperties(Class beanClass, String[] includedProperties, String[] excludedProperties, String prefix, BeanPropertyProcessor processor) throws BeanUtilsException
      Processes the properties of a given bean class with provided accessors, including and excluding properties, using the given prefix and calling the provided BeanPropertyProcessor with each valid property.
      Parameters:
      beanClass - The class of the bean to process.
      includedProperties - An array of property names to include, or null if all properties should be included.
      excludedProperties - An array of property names to exclude, or null if no properties should be excluded.
      prefix - A string to prepend to each property name when processing.
      processor - The BeanPropertyProcessor to call for each valid property.
      Throws:
      BeanUtilsException - If an error occurs while processing the properties, such as an invalid property name or an error invoking a property method.
      Since:
      1.0

    • processProperties

      public static void processProperties(BeanUtils.Accessors accessors, Class beanClass, String[] includedProperties, String[] excludedProperties, String prefix, BeanPropertyProcessor processor) throws BeanUtilsException
      Processes the properties of a given bean class with the provided accessors, including and excluding properties, using the given prefix and calling the provided BeanPropertyProcessor with each valid property.
      Parameters:
      accessors - The Accessors to use when processing properties (either GETTERS_SETTERS or FIELDS).
      beanClass - The class of the bean to process.
      includedProperties - An array of property names to include, or null if all properties should be included.
      excludedProperties - An array of property names to exclude, or null if no properties should be excluded.
      prefix - A string to prepend to each property name when processing.
      processor - The BeanPropertyProcessor to call for each valid property.
      Throws:
      BeanUtilsException - If an error occurs while processing the properties, such as an invalid property name or an error invoking a property method.
      Since:
      1.0

    • processPropertyValues

      public static void processPropertyValues(Object bean, String[] includedProperties, String[] excludedProperties, String prefix, BeanPropertyValueProcessor processor) throws BeanUtilsException
      Processes the property values of a bean based on the provided parameters.
      Parameters:
      bean - the bean whose properties will be processed
      includedProperties - an array of property names to include in the processing
      excludedProperties - an array of property names to exclude from the processing
      prefix - a prefix to add to all processed property names
      processor - a processor function that will handle each property value
      Throws:
      BeanUtilsException - if an error occurs during property processing
      Since:
      1.0

    • processPropertyValues

      public static void processPropertyValues(BeanUtils.Accessors accessors, Object bean, String[] includedProperties, String[] excludedProperties, String prefix, BeanPropertyValueProcessor processor) throws BeanUtilsException
      Processes the property values of a bean based on the provided parameters, using the specified Accessors enum value.
      Parameters:
      accessors - the Accessors enum value to use for getting property values
      bean - the bean whose properties will be processed
      includedProperties - an array of property names to include in the processing
      excludedProperties - an array of property names to exclude from the processing
      prefix - a prefix to add to all processed property names
      processor - a processor function that will handle each property value
      Throws:
      BeanUtilsException - if an error occurs during property processing
      Since:
      1.0

    • countProperties

      public static int countProperties(Class beanClass, String[] includedProperties, String[] excludedProperties, String prefix) throws BeanUtilsException
      Counts the number of properties that match the given criteria for a specified bean class.
      Parameters:
      beanClass - the bean class to examine
      includedProperties - an array of property names to include in the count
      excludedProperties - an array of property names to exclude from the count
      prefix - a prefix to add to all property names being counted
      Returns:
      the number of properties that match the given criteria
      Throws:
      BeanUtilsException - if an error occurs during property counting
      Since:
      1.0

    • countProperties

      public static int countProperties(BeanUtils.Accessors accessors, Class beanClass, String[] includedProperties, String[] excludedProperties, String prefix) throws BeanUtilsException
      Counts the number of properties that match the given criteria for a specified bean class, using the specified Accessors enum value.
      Parameters:
      accessors - the Accessors enum value to use for getting property values
      beanClass - the bean class to examine
      includedProperties - an array of property names to include in the count
      excludedProperties - an array of property names to exclude from the count
      prefix - a prefix to add to all property names being counted
      Returns:
      the number of properties that match the given criteria
      Throws:
      BeanUtilsException - if an error occurs during property counting
      Since:
      1.0

    • getPropertyValue

      public static Object getPropertyValue(Object bean, String name) throws BeanUtilsException
      Returns the value of the property with the given name from the specified bean. Throws an exception if the property does not exist or is not readable.

      The value of an Optional getter will be unwrapped, so that an empty Optional results in null.

      Parameters:
      bean - The bean instance to retrieve the property value from.
      name - The name of the property to retrieve.
      Returns:
      The value of the property.
      Throws:
      BeanUtilsException - If the bean is null, is a class and not an instance, or if the property does not exist or is not readable.
      Since:
      1.0

    • setPropertyValue

      public static void setPropertyValue(Object bean, String name, Object value) throws BeanUtilsException
      Sets the value of the property with the given name in the specified bean. Throws an exception if the property does not exist or is not writable.

      When the property only has an Optional getter, the plain-typed setter that RIFE2 pairs with it will be used, while a setter that declares an Optional parameter will receive the value wrapped.

      Parameters:
      bean - The bean instance to set the property value on.
      name - The name of the property to set.
      value - The value to set the property to.
      Throws:
      BeanUtilsException - If the bean is null, is a class and not an instance, or if the property does not exist or is not writable.
      Since:
      1.0

    • getPropertyType

      public static Class getPropertyType(Class beanClass, String name) throws BeanUtilsException
      Returns the class of a property of a bean, given its name.

      The type of an Optional property is the type of the value that the Optional holds, and not Optional itself.

      Parameters:
      beanClass - the class of the bean to search for the property
      name - the name of the property to retrieve the type
      Returns:
      the class of the property
      Throws:
      BeanUtilsException - if the bean doesn't contain the specified property
      IllegalArgumentException - if the bean class or the name are null or empty
      Since:
      1.0

    • getPropertyValues

      public static Map<String,Object> getPropertyValues(Object bean, String[] includedProperties, String[] excludedProperties, String prefix) throws BeanUtilsException
      Returns the values of the properties of a bean as a map, given an optional prefix and inclusive/exclusive property filters.
      Parameters:
      bean - the bean to get the properties from
      includedProperties - an array of the property names to include in the result map
      excludedProperties - an array of the property names to exclude from the result map
      prefix - an optional prefix to add to the property names in the result map
      Returns:
      a map containing the property values of the bean
      Throws:
      BeanUtilsException - if there was an error while retrieving the property values
      Since:
      1.0

    • getPropertyValues

      public static Map<String,Object> getPropertyValues(BeanUtils.Accessors accessors, Object bean, String[] includedProperties, String[] excludedProperties, String prefix) throws BeanUtilsException
      Returns the values of the properties of a bean as a map, given an optional prefix and inclusive/exclusive property filters and a custom set of accessors.
      Parameters:
      accessors - the Accessors object to use to retrieve the property values
      bean - the bean to get the properties from
      includedProperties - an array of the property names to include in the result map
      excludedProperties - an array of the property names to exclude from the result map
      prefix - an optional prefix to add to the property names in the result map
      Returns:
      a map containing the property values of the bean
      Throws:
      BeanUtilsException - if there was an error while retrieving the property values
      Since:
      1.0

    • formatPropertyValue

      public static String formatPropertyValue(Object propertyValue, ConstrainedProperty constrainedProperty)
      Formats a property value based on the given format from a constrained property.

      A null value simply results in null without the format being used. Note that the values of Optional properties have already been unwrapped when RIFE2 reads them.

      Parameters:
      propertyValue - the value of the property to format
      constrainedProperty - the constrained property that contains formatting info
      Returns:
      the formatted value of the property; or null when the value is null
      Since:
      1.0

    • getPropertyTypes

      public static Map<String,Class> getPropertyTypes(Class beanClass, String[] includedProperties, String[] excludedProperties, String prefix) throws BeanUtilsException
      Returns a map of property names and their corresponding types for the given bean class, based on the included/excluded properties and prefix.
      Parameters:
      beanClass - the class for which to retrieve property types
      includedProperties - the list of property names to include
      excludedProperties - the list of property names to exclude
      prefix - the prefix to use when filtering properties
      Returns:
      a map of property names and their corresponding types for the given bean class
      Throws:
      BeanUtilsException - if an error occurs during property retrieval
      Since:
      1.0

    • getPropertyTypes

      public static Map<String,Class> getPropertyTypes(BeanUtils.Accessors accessors, Class beanClass, String[] includedProperties, String[] excludedProperties, String prefix) throws BeanUtilsException
      Returns a map of property names and their corresponding types for the given bean class, based on the included/excluded properties and prefix, using the specified accessors.
      Parameters:
      accessors - the accessor type to use for property retrieval
      beanClass - the class for which to retrieve property types
      includedProperties - the list of property names to include
      excludedProperties - the list of property names to exclude
      prefix - the prefix to use when filtering properties
      Returns:
      a map of property names and their corresponding types for the given bean class
      Throws:
      BeanUtilsException - if an error occurs during property retrieval
      Since:
      1.0

    • getUppercasedBeanProperties

      public static Map<String,PropertyDescriptor> getUppercasedBeanProperties(Class beanClass) throws BeanUtilsException
      Retrieves a map of all the properties of a bean and their descriptors.

      The property names will be uppercased and an exception will be thrown if two properties are equals case-insensitively.

      Parameters:
      beanClass - the class of the bean
      Returns:
      the map of the bean properties
      Throws:
      BeanUtilsException - when an error occurred while obtaining the bean properties
      Since:
      1.0
      See Also:

    • parseDate

      public Object parseDate(String date, Format format) throws ParseException
      Parses the textual representation of the date using a custom format, or by relying on the standard date formats.
      Parameters:
      date - the textual representation of the date
      format - the custom format that should be used for parsing the string representation of the date; or null if the default formats should be used
      Returns:
      the parsed date
      Throws:
      ParseException - if an error occurred when the date was parsed
      Since:
      1.0

    • setUppercasedBeanProperty

      public static void setUppercasedBeanProperty(String propertyName, String[] propertyValues, String propertyNamePrefix, Map<String,PropertyDescriptor> beanProperties, Object beanInstance, Object emptyBean) throws BeanUtilsException
      Set the value of a bean property from an array of strings.

      The values will be converted to the type of the property, which for an Optional property is the type of the value that it holds. When the property only has an Optional getter, the plain-typed setter that RIFE2 pairs with it will be used, while a setter that declares an Optional parameter will receive the converted value wrapped. When an empty value comes from the empty bean and the setter takes a primitive parameter, the property will be left untouched since a primitive can't hold an absent value.

      Parameters:
      propertyName - the name of the property
      propertyValues - the values that will be set, can be null
      propertyNamePrefix - the prefix that the propertyName parameter should have, can be null
      beanProperties - the map of the uppercased bean property names and their descriptors
      beanInstance - the bean instance whose property should be updated
      emptyBean - this bean instance will be used to set the value of the property in case the propertyValues parameter is empty or null, can be null
      Throws:
      BeanUtilsException - when an error occurred while setting the bean property
      Since:
      1.0
      See Also:

    • setUppercasedBeanProperty

      public static void setUppercasedBeanProperty(String propertyName, UploadedFile propertyFile, String propertyNamePrefix, Map<String,PropertyDescriptor> beanProperties, Object beanInstance) throws BeanUtilsException
      Set the value of a bean property from an uploaded file.
      Parameters:
      propertyName - the name of the property
      propertyFile - the file that will be set, can be null
      propertyNamePrefix - the prefix that the propertyName parameter should have, can be null
      beanProperties - the map of the uppercased bean property names and their descriptors
      beanInstance - the bean instance whose property should be updated
      Throws:
      BeanUtilsException - when an error occurred while setting the bean property
      Since:
      1.0
      See Also: