Package org.apache.commons.configuration2.convert

# Interface ConversionHandler

All Known Implementing Classes:
  `DefaultConversionHandler`

public interface ConversionHandler

An interface defining the possible data type conversions supported by the configuration framework.

This interface defines a couple of methods related to different kinds of data type conversion:

- Conversion to an object of a specific type
- Conversion to an array of a specific type
- Conversion to a collection of a specific type

Data type conversion is related to variable substitution (aka interpolation). Before a value can be converted to a target type substitution has to be performed first, and the conversion is done on the resulting value. In order to support this, the conversion methods expect a `ConfigurationInterpolator` object; `Configuration` implementations here pass in their associated instance.

A `Configuration` object is associated with a concrete `ConversionHandler` implementation. Whenever a data type conversion is required it delegates to this handler. By providing a custom `ConversionHandler` object, the type conversion performed by the configuration object can be adapted.

Since:
  2.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<T> T`
  `to(Object src, Class<T> targetCls, ConfigurationInterpolator ci)`
  Converts a single object to the specified target type.
  `Object`
  `toArray(Object src, Class<?> elemClass, ConfigurationInterpolator ci)`
  Converts the given object to an array of the specified element type.
  `<T> void`
  `toCollection(Object src, Class<T> elemClass, ConfigurationInterpolator ci, Collection<T> dest)`
  Converts the given object to a collection of the specified type.

- ## Method Details

  - ### to

    <T> T to(Object src, Class<T> targetCls, ConfigurationInterpolator ci)
    Converts a single object to the specified target type. A concrete implementation has to attempt a conversion. If this is not possible, a `ConversionException` is thrown. It is up to a concrete implementation how null values are handled; a default strategy would be to return null if the source object is null.
    Type Parameters:
      `T` - the type of the desired result
    Parameters:
      `src` - the object to be converted
      `targetCls` - the target class of the conversion
      `ci` - an object for performing variable substitution
    Returns:
      the converted object
    Throws:
      `ConversionException` - if the requested conversion is not possible

  - ### toArray

    Object toArray(Object src, Class<?> elemClass, ConfigurationInterpolator ci)
    Converts the given object to an array of the specified element type. The object can be a single value (for example a String, a primitive, etc.) or a complex object containing multiple values (like a collection or another array). In the latter case all elements contained in the complex object are converted to the target type. If the value(s) cannot be converted to the desired target class, a `ConversionException` is thrown. Note that the result type of this method is `Object`; because this method can also produce arrays of a primitive type the return type `Object[]` cannot be used.
    Parameters:
      `src` - the object to be converted
      `elemClass` - the element class of the resulting array
      `ci` - an object for performing variable substitution
    Returns:
      the array with the converted values
    Throws:
      `ConversionException` - if the conversion of an element is not possible

  - ### toCollection

    <T> void toCollection(Object src, Class<T> elemClass, ConfigurationInterpolator ci, Collection<T> dest)
    Converts the given object to a collection of the specified type. The target collection must be provided (here callers have the option to specify different types of collections like lists or sets). All values contained in the specified source object (or the source object itself if it is a single value) are converted to the desired target class and added to the destination collection. If the conversion of an element is not possible, a `ConversionException` is thrown.
    Type Parameters:
      `T` - the type of the elements of the destination collection
    Parameters:
      `src` - the object to be converted
      `elemClass` - the element class of the destination collection
      `ci` - an object for performing variable substitution
      `dest` - the destination collection