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

    All Methods Instance Methods Abstract Methods
    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 Detail

    - #### 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 (e.g. 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