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