Bean mapper reference documentation

As discribe in the introduction the Bean Mapper utility realize recursive mapping between java beans. The mapping is defined with a Dynamic Specific Language (DSL).

Dynamic specific language

The folowing code snippet show all the statements that can be used in the DSL. As you can see, There are instructions that can be used at Class level and at field level.

ClassMapperBuilder builder = new ClassMapperBuilder()
    .mapping(c1.class, c2.class)
        .mapNullValue()
        .fieldMapping("f1", "f2")
        .exclude("f3");
        .fieldMapping("strings", "strings")
            .collectionHint(TreeSet.class, Class1.class, ArrayList.class, Class2.class)
            .cumulativeCollectionHint(TreeSet.class, Class1.class, ArrayList.class, Class2.class)
            .mapNullValue()
            .mapSubclass()
            .createInstances()
            .conVerter(c)

A maping between 2 classes is always bidirectional: This means you can mapped instances of the source class to instances of destination class as well as instances from destination class to instances of source classes.

Class level mapping instruction

Instruction	Description
*.mapNullValue()*	By default null value from the source class are not mapped to the destination class. This instruction allows the mapping of null value of the attributs of the source class define in the mapping to be mapped to the destination attribut.
*.fieldMapping("f1", "f2")*	Create a mapping between attribut f1 of the source class and property f2 of the destination class.
*.exclude("f1")*	remove the attribut f1 of the source class from the mapping

Field level mapping instruction

Instruction	Description
*.mapNullValue()*	By default null value from the source class are not mapped to the destination class. If the field of the source class is null it will be mapped to the destination field.
*.mapSubclass()*	When the attributs to map are instance of other classes, the mapper will try to find a map to map all the field of the sublclass.
*.createInstances*	When the attributs to map are instance of other classes and the map supclass is set, the create instances will create new instances of destination field.
*.converter(c)*	When a converter is set on a mapping, The source value will be converted before being set to the destination value.
*.collectionHint(SrcCollectionClass, srcElementClass, DestCollectionClass, DestItemClass)*	Define how to map a collection of object.
*.cumulativeCollectionHint(SrcCollectionClass, srcElementClass, DestCollectionClass, DestItemClass)*	Define how to map a collection of object. The cumulatitive collection means : All the elements of the source collection will be added to the destination collection.

Example

We will setup the mapping between SimpleSource and SimpleDest describe below.

public class SimpleSource {
    
    private EnclosedType subTypeField ;
    private String id ;
    private String v2 ;
    private String v3 ;
    private Integer intVal ;
    private List<String> strings ;
    private EnclosedType subclassField ;
    private String srcValue ;
...
}

public class SimpleDest {
    
    private SimpleDestId id ;
    private String v2 ;
    private String v3 ;
    private String destValue ;
    private int intVal ;
    private Set<String> strings ;
    private EnclosedType subTypeField ;
...
}

public class EnclosedType {
    private String field1 ;
    private int field2 ;
...
}

public class SimpleDestId {
    private String v1;
...
}

Create the default mapping

The default mapping is created by the DSL : .mapping(SimpleSource.class, SimpleDest.class)

ClassMapperBuilder builder= new ClassMapperBuilder()
    .mapping(SimpleSource.class, SimpleDest.class);

The previous code will produce the following mapping:

Source field	Destination field
v2	v2
v3	v3
*intVal*	*intVal*

Add non trivial mapping

The DSL instruction .fieldMapping("srcDield", "destField") is used to define a mapping between srcDield of the source class and destField from the destination class.

ClassMapperBuilder builder= new ClassMapperBuilder()
    .mapping(SimpleSource.class, SimpleDest.class)
        .fieldMapping("srcValue", "destValue");

The DSL instruction .fieldMapping("srcValue", "destValue") Add a mapping between the fields srcValue and destValue. The mapping is now as follow :

Source field	Destination field
v2	v2
v3	v3
*intVal*	*intVal*
*srcValue*	*destValue*

Add non trivial mapping (composite field)

To define a composite field we use the dot notation. Then id.v1: will denote the field v1 of the class SimpleDestId referenced in field id of SimpleDest class.

ClassMapperBuilder builder= new ClassMapperBuilder()
    .mapping(SimpleSource.class, SimpleDest.class)
        .fieldMapping("srcValue", "destValue")
        .fieldMapping("id", "id.v1");

The previous code will produce the following mapping :

Source field	Destination field
v2	v2
v3	v3
*intVal*	*intVal*
*srcValue*	*destValue*
id	*id.v1*

Exclude a field from the mapping

The DSL instruction .exclude("srcFieldname") is used to exclude some field from the mapping.

ClassMapperBuilder builder= new ClassMapperBuilder()
    .mapping(SimpleSource.class, SimpleDest.class)
        .fieldMapping("srcValue", "destValue")
        .fieldMapping("id", "id.v1")
        .exclude("v3");

The mapping will be as follow :

Source field	Destination field
v2	v2
*intVal*	*intVal*
*srcValue*	*destValue*
id	*id.v1*

Mapping null value

The DSL instruction mapnull() is used to force mapping of null value. This instruction is available at class level. and at field level. If you use mapnull() at field level, do not specify it a class level.

ClassMapperBuilder builder= new ClassMapperBuilder()
    .mapping(SimpleSource.class, SimpleDest.class)
        .fieldMapping("srcValue", "destValue")
        .fieldMapping("id", "id.v1")
        .fieldMapping("v3", "v3")
            .mapNull();

The previous sample code will map null value from the field v3.

ClassMapperBuilder builder= new ClassMapperBuilder()
    .mapping(SimpleSource.class, SimpleDest.class);
        .mapNull()
        .fieldMapping("srcValue", "destValue")
        .fieldMapping("id", "id.v1") ;

The previous sample code will map null value of all field.

Mapping sub class

The DSL instruction .mabSubclass is used to specify that a given field (instance of a class) will map the field of its class instead of assigning reference to its instance. A map between the source class and the destination class must exist if the source type is different from the destination type.

ClassMapperBuilder builder= new ClassMapperBuilder()
    .mapping(SimpleSource.class, SimpleDest.class)
        .fieldMapping("srcValue", "destValue")
        .fieldMapping("id", "id.v1")
        .fieldMapping("subclassField", "subTypeField")
            .mabSubclass();

Create instances

ClassMapperBuilder builder= new ClassMapperBuilder()
    .mapping(SimpleSource.class, SimpleDest.class)
        .fieldMapping("srcValue", "destValue")
        .fieldMapping("id", "id.v1")
        .fieldMapping("subclassField", "subTypeField")
            .mabSubclass()
                .createInstances();

Collection