Class ConversionHelper
- java.lang.Object
-
- net.sf.jguiraffe.di.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 Summary
Constructors Constructor Description ConversionHelper()
Creates a new instance ofConversionHelper
which does not have a parent.ConversionHelper(ConversionHelper parent)
Creates a new instance ofConversionHelper
and initializes it with the given parent instance.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description <T> T
convert(Class<T> targetClass, Object value)
Performs a type conversion.protected <T> T
convertObject(Class<T> targetClass, Object value)
Performs a type conversion to the given target class if possible.protected org.apache.commons.beanutils.ConvertUtilsBean
getConvertBean()
Returns the helper object for type conversions.ConversionHelper
getParent()
Returns the parent of this instance.void
registerBaseClassConverter(org.apache.commons.beanutils.Converter converter, Class<?> targetClass)
Registers a converter for the given base class and all derived classes.void
registerConverter(org.apache.commons.beanutils.Converter converter, Class<?> targetClass)
Registers a converter for the specified target class.
-
-
-
Constructor Detail
-
ConversionHelper
public ConversionHelper()
Creates a new instance ofConversionHelper
which does not have a parent.
-
ConversionHelper
public ConversionHelper(ConversionHelper parent)
Creates a new instance ofConversionHelper
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 theconvert(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 theregisterConverter(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 handlesjava.util.List
objects and one for genericjava.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, anInjectionException
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 possibleIllegalArgumentException
- 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 byconvert(Class, Object)
if a conversion is actually required. The arguments have already been checked for null. This implementation uses the conversion helper object returned bygetConvertBean()
to do the conversion.- Type Parameters:
T
- the type of the target class- Parameters:
targetClass
- the target class of the conversionvalue
- the value to be converted- Returns:
- the converted value
- Throws:
InjectionException
- if conversion fails
-
-