DefaultConversionHandler (Apache Commons Configuration 2.15.1 API)
Description: declaration: package: org.apache.commons.configuration2.convert, class: DefaultConversionHandler

Package org.apache.commons.configuration2.convert

# Class DefaultConversionHandler

java.lang.Object
org.apache.commons.configuration2.convert.DefaultConversionHandler

All Implemented Interfaces:
  `ConversionHandler`

public class DefaultConversionHandler extends Object implements ConversionHandler

A default implementation of the `ConversionHandler` interface.

This class implements the standard data type conversions as used by `AbstractConfiguration` and derived classes. There is a central conversion method - `convert()` - for converting a passed in object to a given target class. The basic implementation already handles a bunch of standard data type conversions. If other conversions are to be supported, this method can be overridden.

The object passed to `convert()` can be a single value or a complex object (like an array, a collection, etc.) containing multiple values. It lies in the responsibility of `convert()` to deal with such complex objects. The implementation provided by this class tries to extract the first child element and then delegates to `convertValue()` which does the actual conversion.

Since:
  2.0

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `DEFAULT_DATE_FORMAT`
  The default format for dates.
  `static final DefaultConversionHandler`
  `INSTANCE`
  A default instance of this class.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DefaultConversionHandler()`
  Constructs a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected <T> T`
  `convert(Object src, Class<T> targetCls, ConfigurationInterpolator ci)`
  Performs the conversion from the passed in source object to the specified target class.
  `protected <T> T`
  `convertValue(Object src, Class<T> targetCls, ConfigurationInterpolator ci)`
  Performs a conversion of a single value to the specified target class.
  `protected Object`
  `extractConversionValue(Object container, Class<?> targetCls, ConfigurationInterpolator ci)`
  Extracts a single value from a complex object.
  `protected Collection<?>`
  `extractValues(Object source)`
  Extracts all values contained in the given source object and returns them as a flat collection.
  `protected Collection<?>`
  `extractValues(Object source, int limit)`
  Extracts a maximum number of values contained in the given source object and returns them as flat collection.
  `String`
  `getDateFormat()`
  Gets the date format used by this conversion handler.
  `ListDelimiterHandler`
  `getListDelimiterHandler()`
  Gets the `ListDelimiterHandler` used for extracting values from complex objects.
  `protected boolean`
  `isComplexObject(Object src)`
  Tests whether the passed in object is complex (which means that it contains multiple values).
  `protected boolean`
  `isEmptyElement(Object src)`
  Tests whether the passed in object represents an empty element.
  `void`
  `setDateFormat(String dateFormat)`
  Sets the date format to be used by this conversion handler.
  `void`
  `setListDelimiterHandler(ListDelimiterHandler listDelimiterHandler)`
  Sets the `ListDelimiterHandler` used for extracting values from complex objects.
  `<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.

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

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

- ## Field Details

  - ### INSTANCE

    public static final DefaultConversionHandler INSTANCE
    A default instance of this class. Because an instance of this class can be shared between arbitrary objects it is possible to make use of this default instance anywhere.

  - ### DEFAULT_DATE_FORMAT

    public static final String DEFAULT_DATE_FORMAT
    The default format for dates.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### DefaultConversionHandler

    public DefaultConversionHandler()
    Constructs a new instance.

- ## Method Details

  - ### convert

    protected <T> T convert(Object src, Class<T> targetCls, ConfigurationInterpolator ci)
    Performs the conversion from the passed in source object to the specified target class. This method is called for each conversion to be done. The source object has already been passed to the `ConfigurationInterpolator`, so interpolation does not have to be done again. (The passed in `ConfigurationInterpolator` may still be necessary for extracting values from complex objects; it is guaranteed to be non null.) The source object may be a complex object, for example a collection or an array. This base implementation checks whether the source object is complex. If so, it delegates to `extractConversionValue(Object, Class, ConfigurationInterpolator)` to obtain a single value. Eventually, `convertValue(Object, Class, ConfigurationInterpolator)` is called with the single value to be converted.
    Type Parameters:
      `T` - the desired target type of the conversion
    Parameters:
      `src` - the source object to be converted
      `targetCls` - the desired target class
      `ci` - the `ConfigurationInterpolator` (not null)
    Returns:
      the converted value
    Throws:
      `ConversionException` - if conversion is not possible

  - ### convertValue

    protected <T> T convertValue(Object src, Class<T> targetCls, ConfigurationInterpolator ci)
    Performs a conversion of a single value to the specified target class. The passed in source object is guaranteed to be a single value, but it can be null. Derived classes that want to extend the available conversions, but are happy with the handling of complex objects, just need to override this method.
    Type Parameters:
      `T` - the desired target type of the conversion
    Parameters:
      `src` - the source object (a single value)
      `targetCls` - the target class of the conversion
      `ci` - the `ConfigurationInterpolator` (not null)
    Returns:
      the converted value
    Throws:
      `ConversionException` - if conversion is not possible

  - ### extractConversionValue

    protected Object extractConversionValue(Object container, Class<?> targetCls, ConfigurationInterpolator ci)
    Extracts a single value from a complex object. This method is called by `convert()` if the source object is complex. This implementation extracts the first value from the complex object and returns it.
    Parameters:
      `container` - the complex object
      `targetCls` - the target class of the conversion
      `ci` - the `ConfigurationInterpolator` (not null)
    Returns:
      the value to be converted (may be null if no values are found)

  - ### extractValues

    protected Collection<?> extractValues(Object source)
    Extracts all values contained in the given source object and returns them as a flat collection.
    Parameters:
      `source` - the source object (may be a single value or a complex object)
    Returns:
      a collection with all extracted values

  - ### extractValues

    protected Collection<?> extractValues(Object source, int limit)
    Extracts a maximum number of values contained in the given source object and returns them as flat collection. This method is useful if the caller only needs a subset of values, for example only the first one.
    Parameters:
      `source` - the source object (may be a single value or a complex object)
      `limit` - the number of elements to extract
    Returns:
      a collection with all extracted values

  - ### getDateFormat

    public String getDateFormat()
    Gets the date format used by this conversion handler.
    Returns:
      the date format

  - ### getListDelimiterHandler

    public ListDelimiterHandler getListDelimiterHandler()
    Gets the `ListDelimiterHandler` used for extracting values from complex objects.
    Returns:
      the `ListDelimiterHandler` used for extracting values from complex objects, never null.
    Since:
      2.9.0

  - ### isComplexObject

    protected boolean isComplexObject(Object src)
    Tests whether the passed in object is complex (which means that it contains multiple values). This method is called by `convert(Object, Class, ConfigurationInterpolator)` to figure out whether a actions are required to extract a single value from a complex source object. This implementation considers the following objects as complex:
    - `Iterable` objects
    - `Iterator` objects
    - Arrays
    Parameters:
      `src` - the source object
    Returns:
      true if this is a complex object, false otherwise

  - ### isEmptyElement

    protected boolean isEmptyElement(Object src)
    Tests whether the passed in object represents an empty element. This method is called by conversion methods to arrays or collections. If it returns true, the resulting array or collection will be empty. This implementation returns true if and only if the passed in object is an empty string. With this method it can be controlled if and how empty elements in configurations are handled.
    Parameters:
      `src` - the object to be tested
    Returns:
      a flag whether this object is an empty element

  - ### setDateFormat

    public void setDateFormat(String dateFormat)
    Sets the date format to be used by this conversion handler. This format is applied by conversions to `Date` or `Calendar` objects. The string is passed to the `SimpleDateFormat` class, so it must be compatible with this class. If no date format has been set, a default format is used.
    Parameters:
      `dateFormat` - the date format string
    See Also:
      - `DEFAULT_DATE_FORMAT`

  - ### setListDelimiterHandler

    public void setListDelimiterHandler(ListDelimiterHandler listDelimiterHandler)
    Sets the `ListDelimiterHandler` used for extracting values from complex objects.
    Parameters:
      `listDelimiterHandler` - the `ListDelimiterHandler` used for extracting values from complex objects. Setting the value to null resets the value to its default.
    Since:
      2.9.0

  - ### to

    public <T> T to(Object src, Class<T> targetCls, ConfigurationInterpolator ci)
    Description copied from interface: `ConversionHandler`
    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.
    Specified by:
      `to` in interface `ConversionHandler`
    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

  - ### toArray

    public 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. This implementation extracts all values stored in the passed in source object, converts them to the target type, and adds them to a result array. Arrays of objects and of primitive types are supported. If the source object is null, result is null, too.
    Specified by:
      `toArray` in interface `ConversionHandler`
    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

  - ### toCollection

    public <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. This implementation extracts all values stored in the passed in source object, converts them to the target type, and adds them to the target collection. The target collection must not be null. If the source object is null, nothing is added to the collection.
    Specified by:
      `toCollection` in interface `ConversionHandler`
    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
    Throws:
      `IllegalArgumentException` - if the target collection is null