Class ConversionHelper


  • public class ConversionHelper
    extends Object

    A helper class providing functionality related to data type conversion and registration of custom converters.

    The conversion of data types - e.g. for properties or method parameters - is an important feature: Because beans to be managed by the dependency injection framework are typically defined in XML builder scripts all property values or method parameters are initially strings. The framework has then to find appropriate methods compatible with the specified parameters. If necessary, a type conversion of the values involved has to be performed.

    This class uses Commons BeanUtils for implementing type conversion facilities. The BeanUtils library allows defining custom type converters. Such converters can be registered at an instance of this class to enhance the type conversion capabilities.

    Objects of this class can be connected in a hierarchical way: an instance can have a parent. If a required type converter is not found in this instance, the parent's converters are searched. This allows for instance to define base converters on a top-level instance. Child instances can define specialized converters and even override converters of their parents.

    Implementation note: This class is thread-safe.

    Version:
    $Id: ConversionHelper.java 205 2012-01-29 18:29:57Z oheger $
    Author:
    Oliver Heger
    • Constructor Detail

      • ConversionHelper

        public ConversionHelper()
        Creates a new instance of ConversionHelper which does not have a parent.
      • ConversionHelper

        public ConversionHelper​(ConversionHelper parent)
        Creates a new instance of ConversionHelper and initializes it with the given parent instance. If the parent is defined, it may be queried for type converters if this instance cannot resolve specific data types.
        Parameters:
        parent - the parent instance (may be null)
    • Method Detail

      • getParent

        public ConversionHelper getParent()
        Returns the parent of this instance. This may be null if no parent has been set.
        Returns:
        the parent
      • registerConverter

        public final void registerConverter​(org.apache.commons.beanutils.Converter converter,
                                            Class<?> targetClass)
        Registers a converter for the specified target class. This converter is used by the convert(Class, Object) method if a conversion to the specified target class is needed.
        Parameters:
        converter - the converter to be registered (must not be null)
        targetClass - the target class of the converter (must not be null)
        Throws:
        IllegalArgumentException - if a required parameter is missing
      • registerBaseClassConverter

        public final void registerBaseClassConverter​(org.apache.commons.beanutils.Converter converter,
                                                     Class<?> targetClass)
        Registers a converter for the given base class and all derived classes. If a data conversion is to be performed, it is checked first whether a specific converter for the target class has been registered (using the registerConverter(Converter, Class) method). If this is the case, this converter is used. Otherwise, it is checked whether a converter has been registered using this method whose target class is a super class of the desired target class. If this is the case, this converter is invoked. With this method converters for whole class hierarchies can be registered. This can be useful if all members of the hierarchy require a similar conversion. An example are enumeration classes. Base class converters are checked in reverse order they have been registered. So if they form a hierarchy themselves, the least specific converter should be registered first, followed by more specific ones. For instance, consider some base class converters dealing with collection classes. There may be one converter that handles java.util.List objects and one for generic java.util.Collection objects. In this scenario the collection converter has to be registered first followed by the specific one for lists. Otherwise, the generic collection converter will also be used for lists. This reverse order approach makes it possible for applications to override default base class converters with their own implementations: if custom converters are added later, they take precedence over the already registered converters.
        Parameters:
        converter - the converter to be registered (must not be null)
        targetClass - the target class of the converter (must not be null)
        Throws:
        IllegalArgumentException - if a required parameter is missing
      • convert

        public <T> T convert​(Class<T> targetClass,
                             Object value)
        Performs a type conversion. This method tries to convert the specified value to the given target class. Under the hood converters of the Commons BeanUtils library are used to actually perform the conversion. If custom data types are involved, specialized converters can be registered. If no conversion is possible, an InjectionException exception is thrown.
        Type Parameters:
        T - the type of the target class
        Parameters:
        targetClass - the target class (must not be null)
        value - the value to be converted
        Returns:
        the converted value
        Throws:
        InjectionException - if no conversion is possible
        IllegalArgumentException - if the target class is null
      • getConvertBean

        protected org.apache.commons.beanutils.ConvertUtilsBean getConvertBean()
        Returns the helper object for type conversions.
        Returns:
        the ConvertUtilsBean object responsible for conversions
      • convertObject

        protected <T> T convertObject​(Class<T> targetClass,
                                      Object value)
        Performs a type conversion to the given target class if possible. This method is called by convert(Class, Object) if a conversion is actually required. The arguments have already been checked for null. This implementation uses the conversion helper object returned by getConvertBean() to do the conversion.
        Type Parameters:
        T - the type of the target class
        Parameters:
        targetClass - the target class of the conversion
        value - the value to be converted
        Returns:
        the converted value
        Throws:
        InjectionException - if conversion fails