org.omnaest.utils.beans.replicator
Class BeanReplicator<FROM,TO>

java.lang.Object
  org.omnaest.utils.beans.replicator.BeanReplicator<FROM,TO>

Type Parameters:

FROM -

TO -

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

BeanCopier

public class BeanReplicator<FROM,TO>
extends Object
implements Serializable

General

A BeanReplicator allows to copy(Object, Object) or clone(Object) instances from one type to another type.

By default the BeanReplicator maps similar named and typed properties to each other. The declare(Declaration) method allows to specify in more detail how the replication of a target instance takes place.

Mappings

Mappings can be done from

• Java bean to Java bean
• Java bean to Map<String,Object>
• Map<String,Object> to Java bean
• Map to Map / SortedMap
• List to List / Set / Collection / Array
• Set to List / Set / Collection / Array
• Collection to List / Set / Collection / Array
• Iterable to List / Set / Collection / Array
• Array to List / Set / Collection / Array

Some primitive type mappings like String to Long conversions are done automatically.

Proxy generation

If a target type is an interface, the BeanReplicator will try to generate an proxy implementation on the fly which will act like a normal bean. Of course such conversions are much slower, than normal bean to bean copy actions.

Exception handling

If one ore more properties can not be matched, the BeanReplicator throws internally NoMatchingPropertiesExceptions which are given to any ExceptionHandler set with setExceptionHandler(ExceptionHandler).
Unexpected exceptions will be catched and wrapped into a CopyException and given to the set ExceptionHandler. The BeanReplicator methods itself will never throw any Exception.

Thread safety

The BeanReplicator instance is thread safe in its copy(Object, Object) and clone(Object) methods. The declare(Declaration) method is NOT thread safe and the modification of any BeanReplicator.Declaration should be strongly avoided during any copy(Object, Object) or clone(Object) invocation.

Performance

Even with its very strong mapping capabilities the BeanReplicator is still about 2-5 times faster than the Apache Commons BeanUtils.copyProperties(Object, Object)

For about 1000000 clone invocations it needs about 5-10 seconds. Based on simple beans with a hand full of primitive properties.

The direct getter setter invocation for the same amount of beans takes about 100 ms!!

Code examples

Copy example:

 {
   BeanReplicator<BeanFrom, BeanTo> beanReplicator = new BeanReplicator<BeanFrom, BeanTo>( BeanFrom.class, BeanTo.class );
   final BeanFrom simpleBean = new BeanFrom();
   final TestSimpleBeanTo clone = new TestSimpleBeanTo();
   beanReplicator.copy( simpleBean, clone );
 }
 

Clone example:

 {
   BeanReplicator<BeanFrom, BeanTo> beanReplicator = new BeanReplicator<BeanFrom, BeanTo>( BeanFrom.class, BeanTo.class );
   final BeanFrom simpleBean = new BeanFrom();
   final BeanTo clone = beanReplicator.clone( simpleBean );
 }
 

Remapping example:

 Source bean:  
 |--Bean0From bean0From
    |--Bean1From bean1From
       |--Bean2From bean2From
          |--String fieldForLong
          |--String fieldString1
          |--String fieldString2
 
  Target bean: 
  |-- Bean0To bean0To
    |--Bean1To bean1To
       |--Bean2To bean2To
          |--long fieldLong
          |--String fieldString1
          |--String fieldString2
 

 beanReplicator.declare( new Declaration()
 {
   @Override
   public void declare( DeclarationSupport support )
   {
     support.addTypeMapping( Bean1From.class, Bean1To.class );
     support.addPropertyNameMapping( "bean1From", "bean1To" );
     
     support.addTypeMappingForPath( "bean1From", Bean2From.class, Bean2To.class );
     support.addPropertyNameMapping( "bean1From", "bean2From", "bean2To" );
     
     support.addTypeAndPropertyNameMapping( "bean1From.bean2From", String.class, "fieldForLong", Long.class, "fieldLong" );
   }
 } );
 

Author:

Omnaest

See Also:

BeanReplicator.DeclarationSupport, BeanReplicator.Declaration, declare(Declaration), setExceptionHandler(ExceptionHandler), Serialized Form

Nested Class Summary

static interface	BeanReplicator.ConverterPipeDeclarer
static interface	BeanReplicator.Declaration A BeanReplicator.Declaration allows to declare several kinds of mappings a BeanReplicator should rely on.
static interface	BeanReplicator.DeclarationSupport The BeanReplicator.DeclarationSupport allows to add e.g. type to type or property name mappings, ElementConverter pipes, preservations, ...
static interface	BeanReplicator.PipeBuilder<FROM,TO> The BeanReplicator.PipeBuilder allows to construct a pipe from a given type to another over one or multiple ElementConverter instances.

Constructor Summary

BeanReplicator(Class<? super FROM> sourceType, Class<? extends TO> targetType)

Method Summary

TO	clone(FROM source) Clones a given source instance into its target instance representation
void	copy(FROM source, TO target) Copies from a given source instance to a given target instance
BeanReplicator<FROM,TO>	declare(BeanReplicator.Declaration declaration) Allows the specify a mapping BeanReplicator.Declaration BeanReplicator.Declaration have to be made before any call to copy(Object, Object) or clone(Object)
BeanReplicator<FROM,TO>	setExceptionHandler(ExceptionHandler exceptionHandler) The given ExceptionHandler should handle any CopyException and PreparedBeanCopier.NonMatchingPropertyException

Methods inherited from class java.lang.Object

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

Constructor Detail

BeanReplicator

public BeanReplicator(Class<? super FROM> sourceType,
                      Class<? extends TO> targetType)

Parameters:

sourceType -

targetType -

See Also:

BeanReplicator

Method Detail

clone

public TO clone(FROM source)

Clones a given source instance into its target instance representation

Parameters:

source -

Returns:

See Also:

copy(Object, Object)

copy

public void copy(FROM source,
                 TO target)

Copies from a given source instance to a given target instance

Parameters:

source -

target -

See Also:

clone(Object)

declare

public BeanReplicator<FROM,TO> declare(BeanReplicator.Declaration declaration)

Allows the specify a mapping BeanReplicator.Declaration

BeanReplicator.Declaration have to be made before any call to copy(Object, Object) or clone(Object)

Parameters:

declaration - BeanReplicator.Declaration

Returns:

this

setExceptionHandler

public BeanReplicator<FROM,TO> setExceptionHandler(ExceptionHandler exceptionHandler)

The given ExceptionHandler should handle any CopyException and PreparedBeanCopier.NonMatchingPropertyException

Parameters:

exceptionHandler -

Returns:

this