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 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

      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