net.sf.beanlib.provider
Class BeanPopulator

java.lang.Object
  net.sf.beanlib.provider.BeanPopulator

All Implemented Interfaces:

BeanPopulatorBaseSpi, BeanPopulatorSpi

@NotThreadSafe
public class BeanPopulator
extends Object
implements BeanPopulatorSpi

Default implementation of BeanPopulatorSpi.

A Bean Populator can be used to populate the properties from a JavaBean instance to another JavaBean instance. For example,

 Bean from = ...
 Bean to = ...
 new BeanPopulator(from, to).populate();
 

By default, every public setter method of the target JavaBean is invoked with the value retrieved from the corresponding public getter method (of the same property name and type) of the source JavaBean.

How the set of setter methods and getter methods are determined can be overridden via the methods initSetterMethodCollector(BeanMethodCollector) and initReaderMethodFinder(BeanMethodFinder) before the populate() method is invoked.

During the property propagation process, various options exist to override the default behavior:

1. A DetailedPropertyFilter can be used to control whether a specific JavaBean property should be propagated across.
   See initDetailedPropertyFilter(DetailedPropertyFilter).
   By default, there is no detailed bean property selector configured.
2. Similar to DetailedPropertyFilter but with a simpler API, a PropertyFilter can be used to control whether a specific JavaBean property should be propagated across.
   See initPropertyFilter(PropertyFilter).
   By default, there is no bean property selector configured.
3. A BeanSourceHandler can be used to act as a call-back (to produce whatever side-effects deemed necessary) after the property value has been retrieved from the source bean, but before being propagated across to the target bean.
   See initBeanSourceHandler(BeanSourceHandler).
   By default, there is no bean source handler configured.
4. A Transformable can be used to transform and replace the property value to be propagated across to the target bean.
   See initTransformer(Transformable).
   By default, there is no transformer configured.
5. A BeanPopulationExceptionHandler can be used to handle any exception thrown.
   See initBeanPopulationExceptionHandler(BeanPopulationExceptionHandler) and BeanPopulationExceptionHandler.
   By default, an abort policy is used in that any such exception will cause the propagation to terminate immediately, and the exception itself will get bubbled up as an unchecked exception.

Finally, all these options are grouped as a base configuration, which can be alternatively changed via initBeanPopulatorBaseConfig(BeanPopulatorBaseConfig).

Author:

Joe D. Velopar

Nested Class Summary

static class

BeanPopulator.Factory Bean Populator Factory, which implements the general factory interface of a BeanPopulatorSpi instance.

Field Summary

private BeanPopulatorBaseConfig	baseConfig
static BeanPopulator.Factory	factory
private Object	fromBean
private org.apache.log4j.Logger	log
private Object	toBean
private Transformable	transformer

Constructor Summary

BeanPopulator(Object fromBean, Object toBean)

Method Summary

private <T> void	doit(Method setterMethod, Method readerMethod, Class<T> paramType, String propertyName)
BeanPopulationExceptionHandler	getBeanPopulationExceptionHandler() Returns the exception handler configured for bean population.
BeanPopulatorBaseConfig	getBeanPopulatorBaseConfig() Notes if the returned base config is modified, a subsequent initBeanPopulatorBaseConfig(BeanPopulatorBaseConfig) needs to be invoked to keep the configuration in sync.
BeanSourceHandler	getBeanSourceHandler() Returns the call-back configured that would be invoked after the property value has been retrieved from the source bean, but before being propagated across to the target bean.
private BeanTransformerSpi	getBeanTransformerSpi()
DetailedPropertyFilter	getDetailedPropertyFilter() Returns the detailed property filter configured.
PropertyFilter	getPropertyFilter() Returns the property filter configured.
BeanMethodFinder	getReaderMethodFinder() Returns the finder configured to find the property getter methods of a source JavaBean.
BeanMethodCollector	getSetterMethodCollector() Returns the collector configured to collect the property setter methods of a target JavaBean.
Transformable	getTransformer() Returns the transformer used by this bean populator.
BeanPopulator	initBeanPopulationExceptionHandler(BeanPopulationExceptionHandler beanPopulationExceptionHandler) Used to configure a handler to handle any exception thrown.
BeanPopulator	initBeanPopulatorBaseConfig(BeanPopulatorBaseConfig baseConfig) Used to conveniently provide all the other configuration options as a single configuration object.
BeanPopulator	initBeanSourceHandler(BeanSourceHandler beanSourceHandler) Used to configure a call-back (to produce whatever side-effects deemed necessary) that is invoked after the property value has been retrieved from the source bean, but before being propagated across to the target bean.
BeanPopulator	initDebug(boolean debug) Used to control whether debug messages should be logged.
BeanPopulator	initDetailedPropertyFilter(DetailedPropertyFilter detailedPropertyFilter) Used to configure a detailed prperty filter (which has more context information) to determine whether a specific property should be propagated from the source bean to the target bean.
BeanPopulator	initPropertyFilter(PropertyFilter propertyFilter) Used to configure a property filter to determine whether a specific property should be propagated from a source bean to a target bean.
BeanPopulator	initReaderMethodFinder(BeanMethodFinder readerMethodFinder) Used to configure a finder to find the property getter methods of a source JavaBean.
BeanPopulator	initSetterMethodCollector(BeanMethodCollector setterMethodCollector) Used to configure a collector to collect the property setter methods of a target JavaBean.
BeanPopulator	initTransformer(Transformable transformer) Used to configure a transformer to transform a property value read from a source JavaBean into a value to be to set the corresponding property of a target JavaBean.
private Object	invokeMethodAsPrivileged(Object target, Method method, Object[] args) Invoke the given method as a privileged action, if necessary.
boolean	isDebug() Returns true if debug message logging is on; false otherwise.
<T> T	populate() Propagates properties from the source JavaBean to the target JavaBean.
private void	processSetterMethod(Method setterMethod) Processes a specific setter method for the toBean.

Methods inherited from class java.lang.Object

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

Field Detail

factory

public static final BeanPopulator.Factory factory

log

private final org.apache.log4j.Logger log

fromBean

private final Object fromBean

toBean

private final Object toBean

baseConfig

private BeanPopulatorBaseConfig baseConfig

transformer

private Transformable transformer

Constructor Detail

BeanPopulator

public BeanPopulator(Object fromBean,
                     Object toBean)

Parameters:

fromBean - from bean

toBean - to bean

Method Detail

getBeanTransformerSpi

private BeanTransformerSpi getBeanTransformerSpi()

processSetterMethod

private void processSetterMethod(Method setterMethod)

Processes a specific setter method for the toBean.

Parameters:

setterMethod - a specific method of the toBean

doit

private <T> void doit(Method setterMethod,
                      Method readerMethod,
                      Class<T> paramType,
                      String propertyName)

invokeMethodAsPrivileged

private Object invokeMethodAsPrivileged(Object target,
                                        Method method,
                                        Object[] args)

Invoke the given method as a privileged action, if necessary.

getTransformer

public Transformable getTransformer()

Description copied from interface: BeanPopulatorSpi

Returns the transformer used by this bean populator.

Specified by:

getTransformer in interface BeanPopulatorSpi

initTransformer

public BeanPopulator initTransformer(Transformable transformer)

Description copied from interface: BeanPopulatorSpi

Used to configure a transformer to transform a property value read from a source JavaBean into a value to be to set the corresponding property of a target JavaBean.

Specified by:

initTransformer in interface BeanPopulatorSpi

Parameters:

transformer - is used to transform every property value read from a source JavaBean into a value to be to set the corresponding property of a target JavaBean.

Returns:

the current object (ie this) for method chaining purposes.

populate

public <T> T populate()

Description copied from interface: BeanPopulatorSpi

Propagates properties from the source JavaBean to the target JavaBean.

Specified by:

populate in interface BeanPopulatorSpi

initPropertyFilter

public BeanPopulator initPropertyFilter(PropertyFilter propertyFilter)

Description copied from interface: BeanPopulatorBaseSpi

Used to configure a property filter to determine whether a specific property should be propagated from a source bean to a target bean.

Specified by:

initPropertyFilter in interface BeanPopulatorBaseSpi

Specified by:

initPropertyFilter in interface BeanPopulatorSpi

Parameters:

propertyFilter - is similar to DetailedPropertyFilter but with a simpler API that is used to control whether a specific property should be propagated from a source bean to a target bean.

Returns:

the current object (ie this) for method chaining purposes.

initBeanSourceHandler

public BeanPopulator initBeanSourceHandler(BeanSourceHandler beanSourceHandler)

Description copied from interface: BeanPopulatorBaseSpi

Used to configure a call-back (to produce whatever side-effects deemed necessary) that is invoked after the property value has been retrieved from the source bean, but before being propagated across to the target bean.

Specified by:

initBeanSourceHandler in interface BeanPopulatorBaseSpi

Specified by:

initBeanSourceHandler in interface BeanPopulatorSpi

Parameters:

beanSourceHandler - can be used to act as a call-back (to produce whatever side-effects deemed necessary) after the property value has been retrieved from the source bean, but before being propagated across to the target bean.

Returns:

the current object (ie this) for method chaining purposes.

initDebug

public BeanPopulator initDebug(boolean debug)

Description copied from interface: BeanPopulatorBaseSpi

Used to control whether debug messages should be logged.

Specified by:

initDebug in interface BeanPopulatorBaseSpi

Specified by:

initDebug in interface BeanPopulatorSpi

Returns:

the current object (ie this) for method chaining purposes.

initDetailedPropertyFilter

public BeanPopulator initDetailedPropertyFilter(DetailedPropertyFilter detailedPropertyFilter)

Description copied from interface: BeanPopulatorBaseSpi

Used to configure a detailed prperty filter (which has more context information) to determine whether a specific property should be propagated from the source bean to the target bean.

Specified by:

initDetailedPropertyFilter in interface BeanPopulatorBaseSpi

Specified by:

initDetailedPropertyFilter in interface BeanPopulatorSpi

Parameters:

detailedPropertyFilter - is used to control whether a specific property should be propagated from the source bean to the target bean.

Returns:

the current object (ie this) for method chaining purposes.

initReaderMethodFinder

public BeanPopulator initReaderMethodFinder(BeanMethodFinder readerMethodFinder)

Description copied from interface: BeanPopulatorBaseSpi

Used to configure a finder to find the property getter methods of a source JavaBean.

Specified by:

initReaderMethodFinder in interface BeanPopulatorBaseSpi

Specified by:

initReaderMethodFinder in interface BeanPopulatorSpi

Parameters:

readerMethodFinder - can be used to find the property getter methods of a source JavaBean.

Returns:

the current object (ie this) for method chaining purposes.

initSetterMethodCollector

public BeanPopulator initSetterMethodCollector(BeanMethodCollector setterMethodCollector)

Description copied from interface: BeanPopulatorBaseSpi

Used to configure a collector to collect the property setter methods of a target JavaBean.

Specified by:

initSetterMethodCollector in interface BeanPopulatorBaseSpi

Specified by:

initSetterMethodCollector in interface BeanPopulatorSpi

Parameters:

setterMethodCollector - can be used to collect the property setter methods of a target JavaBean.

Returns:

the current object (ie this) for method chaining purposes.

initBeanPopulationExceptionHandler

public BeanPopulator initBeanPopulationExceptionHandler(BeanPopulationExceptionHandler beanPopulationExceptionHandler)

Description copied from interface: BeanPopulatorBaseSpi

Used to configure a handler to handle any exception thrown.

Specified by:

initBeanPopulationExceptionHandler in interface BeanPopulatorBaseSpi

Specified by:

initBeanPopulationExceptionHandler in interface BeanPopulatorSpi

Parameters:

beanPopulationExceptionHandler - can be used to handle any exception thrown.

Returns:

the current object (ie this) for method chaining purposes.

initBeanPopulatorBaseConfig

public BeanPopulator initBeanPopulatorBaseConfig(BeanPopulatorBaseConfig baseConfig)

Description copied from interface: BeanPopulatorBaseSpi

Used to conveniently provide all the other configuration options as a single configuration object.

Specified by:

initBeanPopulatorBaseConfig in interface BeanPopulatorBaseSpi

Specified by:

initBeanPopulatorBaseConfig in interface BeanPopulatorSpi

Parameters:

baseConfig - is used to conveniently group all the other initializable options into a single unit.

Returns:

the current object (ie this) for method chaining purposes.

getPropertyFilter

public PropertyFilter getPropertyFilter()

Description copied from interface: BeanPopulatorBaseSpi

Returns the property filter configured.

Specified by:

getPropertyFilter in interface BeanPopulatorBaseSpi

getBeanPopulationExceptionHandler

public BeanPopulationExceptionHandler getBeanPopulationExceptionHandler()

Description copied from interface: BeanPopulatorBaseSpi

Returns the exception handler configured for bean population.

Specified by:

getBeanPopulationExceptionHandler in interface BeanPopulatorBaseSpi

getBeanPopulatorBaseConfig

public BeanPopulatorBaseConfig getBeanPopulatorBaseConfig()

Notes if the returned base config is modified, a subsequent initBeanPopulatorBaseConfig(BeanPopulatorBaseConfig) needs to be invoked to keep the configuration in sync.

Specified by:

getBeanPopulatorBaseConfig in interface BeanPopulatorBaseSpi

getBeanSourceHandler

public BeanSourceHandler getBeanSourceHandler()

Description copied from interface: BeanPopulatorBaseSpi

Returns the call-back configured that would be invoked after the property value has been retrieved from the source bean, but before being propagated across to the target bean.

Specified by:

getBeanSourceHandler in interface BeanPopulatorBaseSpi

isDebug

public boolean isDebug()

Description copied from interface: BeanPopulatorBaseSpi

Returns true if debug message logging is on; false otherwise.

Specified by:

isDebug in interface BeanPopulatorBaseSpi

getDetailedPropertyFilter

public DetailedPropertyFilter getDetailedPropertyFilter()

Description copied from interface: BeanPopulatorBaseSpi

Returns the detailed property filter configured.

Specified by:

getDetailedPropertyFilter in interface BeanPopulatorBaseSpi

getReaderMethodFinder

public BeanMethodFinder getReaderMethodFinder()

Description copied from interface: BeanPopulatorBaseSpi

Returns the finder configured to find the property getter methods of a source JavaBean.

Specified by:

getReaderMethodFinder in interface BeanPopulatorBaseSpi

getSetterMethodCollector

public BeanMethodCollector getSetterMethodCollector()

Description copied from interface: BeanPopulatorBaseSpi

Returns the collector configured to collect the property setter methods of a target JavaBean.

Specified by:

getSetterMethodCollector in interface BeanPopulatorBaseSpi