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 Summary

  Constructors
  Constructor
  Description
  `ConvertUtilsBean()`
  Constructs a bean with standard converters registered

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `convert(Object value)`
  Delegates to the new `convert(Object, Class)` method.
  `<T> Object`
  `convert(Object value, Class<T> targetType)`
  Converts the value to an object of the specified class (if possible).
  `<T> Object`
  `convert(String[] value, Class<T> clazz)`
  Delegates to the new `convert(Object, Class)` method.
  `<R> Object`
  `convert(String value, Class<R> clazz)`
  Delegates to the new `convert(Object, Class)` method.
  `void`
  `deregister()`
  Deregisters all registered `Converter`s, and re-establish the standard Converters.
  `void`
  `deregister(Class<?> clazz)`
  Remove any registered `Converter` for the specified destination `Class`.
  `protected static ConvertUtilsBean`
  `getInstance()`
  Gets singleton instance
  `<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`.
  `<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`.
  `void`
  `register(boolean throwException, boolean defaultNull, int defaultArraySize)`
  Registers the provided converters with the specified defaults.
  `void`
  `register(Converter converter, Class<?> clazz)`
  Registers a custom `Converter` for the specified destination `Class`, replacing any previously registered Converter.

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

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

- ## 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(String[], Class)`

  - ### 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(String[], Class)`

  - ### 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:
      - `convert(String[], Class)`

  - ### deregister

    public void deregister()
    Deregisters all registered `Converter`s, 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` - `true`if 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