Package org.apache.commons.beanutils2

Class ConvertUtilsBean

java.lang.Object
org.apache.commons.beanutils2.ConvertUtilsBean
public class ConvertUtilsBean extends Object
TODO DOCS

2.0

ConvertUtilsBean implementation that delegates convert() methods to the new convert(Object, Class) method.

To configure this implementation for the current context ClassLoader invoke BeanUtilsBean.setInstance(new BeanUtilsBean2());

Pre-2.0

Utility methods for converting String scalar values to objects of the specified Class, String arrays to arrays of the specified Class. The actual Converter instance to be used can be registered for each possible destination Class. Unless you override them, standard Converter instances are provided for all of the following destination Classes:

  • java.lang.BigDecimal (no default value)
  • java.lang.BigInteger (no default value)
  • boolean and java.lang.Boolean (default to false)
  • byte and java.lang.Byte (default to zero)
  • char and java.lang.Character (default to a space)
  • java.lang.Class (no default value)
  • java.awt.Color (no default value)
  • java.awt.Dimension (no default value)
  • double and java.lang.Double (default to zero)
  • float and java.lang.Float (default to zero)
  • int and java.lang.Integer (default to zero)
  • long and java.lang.Long (default to zero)
  • short and java.lang.Short (default to zero)
  • java.lang.String (default to null)
  • java.lang.Enum (default to null)
  • java.io.File (no default value)
  • java.net.InetAddress (no default value)
  • java.util.Locale (no default value)
  • java.nio.file.Path (no default value)
  • java.net.URL (no default value)
  • java.net.URI (no default value)
  • java.util.UUID (no default value)
  • java.sql.Date (no default value)
  • java.sql.Time (no default value)
  • java.sql.Timestamp (no default value)
  • java.time.LocalDate (no default value)
  • java.time.LocalDateTime (no default value)
  • java.time.LocalTime (no default value)
  • java.time.OffsetDateTime (no default value)
  • java.time.OffsetTime (no default value)
  • java.time.ZonedDateTime (no default value)
  • java.time.Duration (no default value)
  • java.time.MonthDay (no default value)
  • java.util.regex.Pattern (no default value)
  • java.time.Period (no default value)
  • java.awt.Point (no default value)
  • java.time.Year (no default value)
  • java.time.YearMonth (no default value)
  • java.time.ZoneId (no default value)
  • java.time.ZoneOffset (no default value)

For backwards compatibility, the standard Converters for primitive types (and the corresponding wrapper classes) return a defined default value when a conversion error occurs. If you prefer to have a ConversionException thrown instead, replace the standard Converter instances with instances created with the zero-arguments constructor. For example, to cause the Converters for integers to throw an exception on conversion errors, you could do this: 

 // No-args constructor gets the version that throws exceptions
 Converter myConverter = new org.apache.commons.beanutils2.converter.IntegerConverter();
 ConvertUtils.register(myConverter, Integer.TYPE); // Native type
 ConvertUtils.register(myConverter, Integer.class); // Wrapper class

Converters generally treat null input as if it were invalid input, that is, they return their default value if one was specified when the converter was constructed, and throw an exception otherwise. If you prefer nulls to be preserved for converters that are converting to objects (not primitives) then register a converter as above, passing a default value of null to the converter constructor (and of course registering that converter only for the .class target).

When a converter is listed above as having no default value, then that converter will throw an exception when passed null or an invalid value as its input. In particular, by default the BigInteger and BigDecimal converters have no default (and are therefore somewhat inconsistent with the other numerical converters which all have zero as their default).

Converters that generate arrays of each of the primitive types are also automatically configured (including String[]). When passed null or invalid input, these return an empty array (not null). See class AbstractArrayConverter for the supported input formats for these converters.

Since:
1.7

  • Constructor Details

    • ConvertUtilsBean

      public ConvertUtilsBean()
      Constructs a bean with standard converters registered

  • Method Details

    • getInstance

      protected static ConvertUtilsBean getInstance()
      Gets singleton instance
      Returns:
      The singleton instance

    • convert

      public String convert(Object value)
      Delegates to the new convert(Object, Class) method.
      Parameters:
      value - Value to be converted (may be null)
      Returns:
      The converted String value or null if value is null
      See Also:

    • convert

      public <T> Object convert(Object value, Class<T> targetType)
      Converts the value to an object of the specified class (if possible). If no converter for the desired target type is registered, the passed in object is returned unchanged.
      Type Parameters:
      T - The Class type.
      Parameters:
      value - Value to be converted (may be null)
      targetType - Class of the value to be converted to (must not be null)
      Returns:
      The converted value
      Throws:
      ConversionException - if thrown by an underlying Converter

    • convert

      public <R> Object convert(String value, Class<R> clazz)
      Delegates to the new convert(Object, Class) method.
      Type Parameters:
      R - the type of the class for the return value.
      Parameters:
      value - Value to be converted (may be null)
      clazz - Java class to be converted to (must not be null)
      Returns:
      The converted value or null if value is null
      See Also:

    • convert

      public <T> Object convert(String[] value, Class<T> clazz)
      Delegates to the new convert(Object, Class) method.
      Type Parameters:
      T - the type of the class for the return value.
      Parameters:
      value - Array of values to be converted
      clazz - Java array or element class to be converted to (must not be null)
      Returns:
      The converted value
      See Also:

    • deregister

      public void deregister()
      Deregisters all registered Converters, and re-establish the standard Converters.

    • deregister

      public void deregister(Class<?> clazz)
      Remove any registered Converter for the specified destination Class.
      Parameters:
      clazz - Class for which to remove a registered Converter

    • lookup

      public <T> Converter<T> lookup(Class<?> sourceType, Class<T> targetType)
      Looks up and return any registered Converter for the specified source and destination class; if there is no registered Converter, return null.
      Type Parameters:
      T - The converter type.
      Parameters:
      sourceType - Class of the value being converted
      targetType - Class of the value to be converted to
      Returns:
      The registered Converter or null if not found

    • lookup

      public <T> Converter<T> lookup(Class<T> clazz)
      Looks up and return any registered Converter for the specified destination class; if there is no registered Converter, return null.
      Type Parameters:
      T - The converter type.
      Parameters:
      clazz - Class for which to return a registered Converter
      Returns:
      The registered Converter or null if not found

    • register

      public void register(boolean throwException, boolean defaultNull, int defaultArraySize)
      Registers the provided converters with the specified defaults.
      Parameters:
      throwException - true if the converters should throw an exception when a conversion error occurs, otherwise false if a default value should be used.
      defaultNull - trueif the standard converters (see registerStandard(boolean, boolean)) should use a default value of null</code>, otherwise <code>false. N.B. This values is ignored if throwException</code> is <code>true
      defaultArraySize - The size of the default array value for array converters (N.B. This values is ignored if throwException</code> is <code>true). Specifying a value less than zero causes a null value to be used for the default.

    • register

      public void register(Converter converter, Class<?> clazz)
      Registers a custom Converter for the specified destination Class, replacing any previously registered Converter.
      Parameters:
      converter - Converter to be registered
      clazz - Destination class for conversions performed by this Converter