net.sf.beanlib.provider
Class BeanTransformer

java.lang.Object
  extended by net.sf.beanlib.provider.replicator.ReplicatorTemplate
      extended by net.sf.beanlib.provider.BeanTransformer
All Implemented Interfaces:
BeanPopulatorBaseSpi, BeanTransformerSpi, Transformable
Direct Known Subclasses:
Hibernate3BeanTransformer

@NotThreadSafe
public class BeanTransformer
extends ReplicatorTemplate
implements BeanTransformerSpi

Default implementation of BeanTransformerSpi. A Bean Transformer can be used to transform object input typically in the form of a property that follows the JavaBean getter/setter convention, on a best attempt basis, into an output object typically used to populate the corresponding property of a target JavaBean.

This class extends ReplicatorTemplate as the implementation typically transforms a JavaBean property by replicating it into a separate instance. The replication is typically recursive in that the whole object graph of the input object is replicated into an equivalent output object graph, resolving circular references as necessary. However, the exact behavior of the replication process including

can be controlled and/or supplemented by the client code via various options:

  1. All the configurable options of BeanPopulatorBaseSpi are available, as the replication of JavaBean properties inevitably involves bean population.
  2. A Bean Transformer adopts a best effort approach to perform object transformation and replication. The default implementations for replicating the common data types such as collection, map, dates, etc. can be selectively overridden via the replicator factory initialization methods:

  3. For anything else that the existing implementation fails to tranform, client can provide one or multiple custom transformer factories via the constructor new BeanTransformer(CustomBeanTransformerSpi.Factory...).

Author:
Joe D. Velopar
See Also:
CustomBeanTransformerSpi

Nested Class Summary
 
Nested classes/interfaces inherited from interface net.sf.beanlib.spi.BeanTransformerSpi
BeanTransformerSpi.Factory
 
Field Summary
private  ArrayReplicatorSpi arrayReplicatable
          Replicator for arrays.
private  BeanPopulatorBaseConfig baseConfig
          Used to contain all the configuration options as a single configuration object.
private  BeanPopulatorSpi.Factory beanPopulatorFactory
          Bean populator factory, which is used to create a bean populator which can then be used to determine whether a specific JavaBean property should be propagated from a source bean to a target bean.
private  BeanReplicatorSpi beanReplicatable
          Replicator for JavaBeans.
private  BlobReplicatorSpi blobReplicatable
          Replicator for blobs.
private  CalendarReplicatorSpi calendarReplicatable
          Replicator for calendars.
private  Map<Object,Object> clonedMap
          Used to contains those objects that have been replicated.
private  CollectionReplicatorSpi collectionReplicatable
          Replicator for collections.
private  CustomBeanTransformerSpi customTransformer
          Custom Transformer.
private  DateReplicatorSpi dateReplicatable
          Replicator for dates.
private  ImmutableReplicatorSpi immutableReplicatable
          Replicator for immutables.
private  MapReplicatorSpi mapReplicatable
          Replicator for maps.
 
Fields inherited from class net.sf.beanlib.provider.replicator.ReplicatorTemplate
log
 
Constructor Summary
  BeanTransformer()
          Constructs with the default BeanPopulator.factory.
protected BeanTransformer(BeanPopulatorSpi.Factory beanPopulatorFactory)
          Constructs with the given bean populator factory, which is used to create a bean populator which can then be used to determine whether a specific JavaBean property should be propagated from a source bean to a target bean.
  BeanTransformer(CustomBeanTransformerSpi.Factory... customBeanTransformerFactories)
          Convenient constructor that both defaults to use BeanPopulator.factory, and allows plugging in one or more custom bean transformer factories that will be chained together.
 
Method Summary
 ArrayReplicatorSpi getArrayReplicatable()
          Returns the current replicator for array.
 BeanPopulationExceptionHandler getBeanPopulationExceptionHandler()
          Returns the exception handler configured for bean population.
 BeanPopulatorBaseConfig getBeanPopulatorBaseConfig()
          Returns all the configuration options as a single configuration object.
 BeanPopulatorSpi.Factory getBeanPopulatorSpiFactory()
          Returns the current bean populator factory, which is used to create a bean populator which can then be used to determine whether a specific JavaBean property should be propagated from a source bean to a target bean.
 BeanReplicatorSpi getBeanReplicatable()
          Returns the current replicator for JavaBeans.
 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.
 BlobReplicatorSpi getBlobReplicatable()
          Returns the current replicator for blobs.
 CalendarReplicatorSpi getCalendarReplicatable()
          Returns the current replicator for calendars.
<K,V> Map<K,V>
getClonedMap()
          Returns a map of those (from-to) objects that have been replicated.
 CollectionReplicatorSpi getCollectionReplicatable()
          Returns the current replicator for collections.
 CustomBeanTransformerSpi getCustomBeanTransformer()
          Returns the customer bean transformer, if any.
 DateReplicatorSpi getDateReplicatable()
          Returns the current replicator for dates.
 DetailedPropertyFilter getDetailedPropertyFilter()
          Returns the detailed property filter configured.
 ImmutableReplicatorSpi getImmutableReplicatable()
          Returns the current replicator for immutables.
 MapReplicatorSpi getMapReplicatable()
          Returns the current replicator for maps.
 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.
 BeanTransformer initArrayReplicatableFactory(ArrayReplicatorSpi.Factory arrayReplicatableFactory)
          Used to initialize the replicator factory for arrays.
 BeanTransformer initBeanPopulationExceptionHandler(BeanPopulationExceptionHandler beanPopulationExceptionHandler)
          Used to configure a handler to handle any exception thrown.
 BeanTransformerSpi initBeanPopulatorBaseConfig(BeanPopulatorBaseConfig baseConfig)
          Used to conveniently provide all the other configuration options as a single configuration object.
 BeanTransformer initBeanReplicatableFactory(BeanReplicatorSpi.Factory objectReplicatableFactory)
          Used to initialize the replicator factory for JavaBean's.
 BeanTransformer 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.
 BeanTransformer initBlobReplicatableFactory(BlobReplicatorSpi.Factory blobReplicatableFactory)
          Used to initialize the replicator factory for blob's.
 BeanTransformerSpi initCalendarReplicatableFactory(CalendarReplicatorSpi.Factory calendarReplicatableFactory)
          Used to initialize the replicator factory for calendars.
 BeanTransformer initCollectionReplicatableFactory(CollectionReplicatorSpi.Factory factory)
          Used to initialize the replicator factory for collections.
 BeanTransformer initCustomTransformerFactory(CustomBeanTransformerSpi.Factory customTransformer)
          Initializes with a custom transformer factory.
 BeanTransformerSpi initDateReplicatableFactory(DateReplicatorSpi.Factory dateReplicatableFactory)
          Used to initialize the replicator factory for dates.
 BeanTransformer initDebug(boolean debug)
          Used to control whether debug messages should be logged.
 BeanTransformer 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.
 BeanTransformer initImmutableReplicatableFactory(ImmutableReplicatorSpi.Factory immutableReplicatableFactory)
          Used to initialize the replicator factory for immutables.
 BeanTransformer initMapReplicatableFactory(MapReplicatorSpi.Factory factory)
          Used to initialize the replicator factory for maps.
 BeanTransformer 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.
 BeanTransformer initReaderMethodFinder(BeanMethodFinder readerMethodFinder)
          Used to configure a finder to find the property getter methods of a source JavaBean.
 BeanTransformer initSetterMethodCollector(BeanMethodCollector setterMethodCollector)
          Used to configure a collector to collect the property setter methods of a target JavaBean.
 boolean isDebug()
          Returns true if debug message logging is on; false otherwise.
 void reset()
          Reset the internal identity maps used to contain objects that have been replicated.
<T> T
transform(Object from, Class<T> toClass, PropertyInfo propertyInfo)
          Returns an object transformed from the input object with the given target class.
 
Methods inherited from class net.sf.beanlib.provider.replicator.ReplicatorTemplate
chooseClass, containsTargetCloned, createToInstance, createToInstance, createToInstanceWithComparator, getCustomerBeanTransformer, getTargetCloned, newInstanceAsPrivileged, populateBean, putTargetCloned, replicate, replicate, replicateByBeanReplicatable, unenhanceObject
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

beanPopulatorFactory

private final BeanPopulatorSpi.Factory beanPopulatorFactory
Bean populator factory, which is used to create a bean populator which can then be used to determine whether a specific JavaBean property should be propagated from a source bean to a target bean.


clonedMap

private Map<Object,Object> clonedMap
Used to contains those objects that have been replicated.


baseConfig

private BeanPopulatorBaseConfig baseConfig
Used to contain all the configuration options as a single configuration object.


customTransformer

private CustomBeanTransformerSpi customTransformer
Custom Transformer. Defaults is a NO_OP.


immutableReplicatable

private ImmutableReplicatorSpi immutableReplicatable
Replicator for immutables.


collectionReplicatable

private CollectionReplicatorSpi collectionReplicatable
Replicator for collections.


mapReplicatable

private MapReplicatorSpi mapReplicatable
Replicator for maps.


arrayReplicatable

private ArrayReplicatorSpi arrayReplicatable
Replicator for arrays.


blobReplicatable

private BlobReplicatorSpi blobReplicatable
Replicator for blobs.


dateReplicatable

private DateReplicatorSpi dateReplicatable
Replicator for dates.


calendarReplicatable

private CalendarReplicatorSpi calendarReplicatable
Replicator for calendars.


beanReplicatable

private BeanReplicatorSpi beanReplicatable
Replicator for JavaBeans.

Constructor Detail

BeanTransformer

public BeanTransformer()
Constructs with the default BeanPopulator.factory.


BeanTransformer

public BeanTransformer(CustomBeanTransformerSpi.Factory... customBeanTransformerFactories)
Convenient constructor that both defaults to use BeanPopulator.factory, and allows plugging in one or more custom bean transformer factories that will be chained together.

See Also:
ChainedCustomBeanTransformer

BeanTransformer

protected BeanTransformer(BeanPopulatorSpi.Factory beanPopulatorFactory)
Constructs with the given bean populator factory, which is used to create a bean populator which can then be used to determine whether a specific JavaBean property should be propagated from a source bean to a target bean.

Method Detail

getBeanPopulatorSpiFactory

public BeanPopulatorSpi.Factory getBeanPopulatorSpiFactory()
Description copied from interface: BeanTransformerSpi
Returns the current bean populator factory, which is used to create a bean populator which can then be used to determine whether a specific JavaBean property should be propagated from a source bean to a target bean.

Specified by:
getBeanPopulatorSpiFactory in interface BeanTransformerSpi

reset

public final void reset()
Description copied from interface: BeanTransformerSpi
Reset the internal identity maps used to contain objects that have been replicated. (Warning: Don't invoke this method unless you really know what you are doing.)

Specified by:
reset in interface BeanTransformerSpi

transform

public final <T> T transform(Object from,
                             Class<T> toClass,
                             PropertyInfo propertyInfo)
Description copied from interface: Transformable
Returns an object transformed from the input object with the given target class.

Specified by:
transform in interface Transformable
Overrides:
transform in class ReplicatorTemplate
Parameters:
from - the input object to be transformed. If propertyInfo is non-null, the input object is a JavaBean property value.
toClass - the target class to be transformed to.
propertyInfo - If null, it means the in object is a root level object. Otherwise, propertyInfo contains information about the input object as a java bean property value to be transformed.
Returns:
the transformed object.

initCustomTransformerFactory

public final BeanTransformer initCustomTransformerFactory(CustomBeanTransformerSpi.Factory customTransformer)
Description copied from interface: BeanTransformerSpi
Initializes with a custom transformer factory.

Specified by:
initCustomTransformerFactory in interface BeanTransformerSpi

initPropertyFilter

public final BeanTransformer 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 BeanTransformerSpi
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 final BeanTransformer 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 BeanTransformerSpi
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 final BeanTransformer 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 BeanTransformerSpi
Returns:
the current object (ie this) for method chaining purposes.

initDetailedPropertyFilter

public final BeanTransformer 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 BeanTransformerSpi
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 final BeanTransformer 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 BeanTransformerSpi
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 final BeanTransformer 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 BeanTransformerSpi
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.

initCollectionReplicatableFactory

public BeanTransformer initCollectionReplicatableFactory(CollectionReplicatorSpi.Factory factory)
Description copied from interface: BeanTransformerSpi
Used to initialize the replicator factory for collections.

Specified by:
initCollectionReplicatableFactory in interface BeanTransformerSpi

getCollectionReplicatable

public CollectionReplicatorSpi getCollectionReplicatable()
Description copied from interface: BeanTransformerSpi
Returns the current replicator for collections.

Specified by:
getCollectionReplicatable in interface BeanTransformerSpi

initMapReplicatableFactory

public BeanTransformer initMapReplicatableFactory(MapReplicatorSpi.Factory factory)
Description copied from interface: BeanTransformerSpi
Used to initialize the replicator factory for maps.

Specified by:
initMapReplicatableFactory in interface BeanTransformerSpi

getMapReplicatable

public MapReplicatorSpi getMapReplicatable()
Description copied from interface: BeanTransformerSpi
Returns the current replicator for maps.

Specified by:
getMapReplicatable in interface BeanTransformerSpi

getClonedMap

public <K,V> Map<K,V> getClonedMap()
Description copied from interface: BeanTransformerSpi
Returns a map of those (from-to) objects that have been replicated. This map is internally used to resolve object identities and circular references in the object graph.

Specified by:
getClonedMap in interface BeanTransformerSpi

initImmutableReplicatableFactory

public BeanTransformer initImmutableReplicatableFactory(ImmutableReplicatorSpi.Factory immutableReplicatableFactory)
Description copied from interface: BeanTransformerSpi
Used to initialize the replicator factory for immutables.

Specified by:
initImmutableReplicatableFactory in interface BeanTransformerSpi

getImmutableReplicatable

public ImmutableReplicatorSpi getImmutableReplicatable()
Description copied from interface: BeanTransformerSpi
Returns the current replicator for immutables.

Specified by:
getImmutableReplicatable in interface BeanTransformerSpi

initArrayReplicatableFactory

public BeanTransformer initArrayReplicatableFactory(ArrayReplicatorSpi.Factory arrayReplicatableFactory)
Description copied from interface: BeanTransformerSpi
Used to initialize the replicator factory for arrays.

Specified by:
initArrayReplicatableFactory in interface BeanTransformerSpi

getArrayReplicatable

public ArrayReplicatorSpi getArrayReplicatable()
Description copied from interface: BeanTransformerSpi
Returns the current replicator for array.

Specified by:
getArrayReplicatable in interface BeanTransformerSpi

initBlobReplicatableFactory

public BeanTransformer initBlobReplicatableFactory(BlobReplicatorSpi.Factory blobReplicatableFactory)
Description copied from interface: BeanTransformerSpi
Used to initialize the replicator factory for blob's.

Specified by:
initBlobReplicatableFactory in interface BeanTransformerSpi

getBlobReplicatable

public BlobReplicatorSpi getBlobReplicatable()
Description copied from interface: BeanTransformerSpi
Returns the current replicator for blobs.

Specified by:
getBlobReplicatable in interface BeanTransformerSpi

initBeanReplicatableFactory

public BeanTransformer initBeanReplicatableFactory(BeanReplicatorSpi.Factory objectReplicatableFactory)
Description copied from interface: BeanTransformerSpi
Used to initialize the replicator factory for JavaBean's.

Specified by:
initBeanReplicatableFactory in interface BeanTransformerSpi

getBeanReplicatable

public BeanReplicatorSpi getBeanReplicatable()
Description copied from interface: BeanTransformerSpi
Returns the current replicator for JavaBeans.

Specified by:
getBeanReplicatable in interface BeanTransformerSpi

initDateReplicatableFactory

public BeanTransformerSpi initDateReplicatableFactory(DateReplicatorSpi.Factory dateReplicatableFactory)
Description copied from interface: BeanTransformerSpi
Used to initialize the replicator factory for dates.

Specified by:
initDateReplicatableFactory in interface BeanTransformerSpi

initCalendarReplicatableFactory

public BeanTransformerSpi initCalendarReplicatableFactory(CalendarReplicatorSpi.Factory calendarReplicatableFactory)
Description copied from interface: BeanTransformerSpi
Used to initialize the replicator factory for calendars.

Specified by:
initCalendarReplicatableFactory in interface BeanTransformerSpi

getDateReplicatable

public DateReplicatorSpi getDateReplicatable()
Description copied from interface: BeanTransformerSpi
Returns the current replicator for dates.

Specified by:
getDateReplicatable in interface BeanTransformerSpi

getCalendarReplicatable

public CalendarReplicatorSpi getCalendarReplicatable()
Description copied from interface: BeanTransformerSpi
Returns the current replicator for calendars.

Specified by:
getCalendarReplicatable in interface BeanTransformerSpi

initBeanPopulationExceptionHandler

public BeanTransformer 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 BeanTransformerSpi
Parameters:
beanPopulationExceptionHandler - can be used to handle any exception thrown.
Returns:
the current object (ie this) for method chaining purposes.

initBeanPopulatorBaseConfig

public BeanTransformerSpi 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 BeanTransformerSpi
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.

getBeanPopulatorBaseConfig

public BeanPopulatorBaseConfig getBeanPopulatorBaseConfig()
Description copied from interface: BeanTransformerSpi
Returns all the configuration options as a single configuration object.

Specified by:
getBeanPopulatorBaseConfig in interface BeanPopulatorBaseSpi
Specified by:
getBeanPopulatorBaseConfig in interface BeanTransformerSpi

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

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

getCustomBeanTransformer

public CustomBeanTransformerSpi getCustomBeanTransformer()
Description copied from interface: BeanTransformerSpi
Returns the customer bean transformer, if any. See BeanTransformerSpi.initCustomTransformerFactory(net.sf.beanlib.spi.CustomBeanTransformerSpi.Factory)

Specified by:
getCustomBeanTransformer in interface BeanTransformerSpi