Interface ConversionHandler

  • All Known Implementing Classes:
    DataConfiguration.DataConversionHandler, 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​(java.lang.Object src, java.lang.Class<T> targetCls, ConfigurationInterpolator ci)
      Converts a single object to the specified target type.
      java.lang.Object toArray​(java.lang.Object src, java.lang.Class<?> elemClass, ConfigurationInterpolator ci)
      Converts the given object to an array of the specified element type.
      <T> void toCollection​(java.lang.Object src, java.lang.Class<T> elemClass, ConfigurationInterpolator ci, java.util.Collection<T> dest)
      Converts the given object to a collection of the specified type.
    • Method Detail

      • to

        <T> T to​(java.lang.Object src,
                 java.lang.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

        java.lang.Object toArray​(java.lang.Object src,
                                 java.lang.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​(java.lang.Object src,
                              java.lang.Class<T> elemClass,
                              ConfigurationInterpolator ci,
                              java.util.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