BeanMapper: Types-aware Property Mapper

BeanMapper: Types-aware Property Mapper for Java (by Phil Sladen)

Introduction

A simple yet powerful way to copy/transform properties from external beans to a local bean, and vice-versa, for convenience and decoupling. Annotations can used to select particular fields to be processed. The main difference between this mapping tool and others is that Field information is required on a target property so that Generic collections are populated/transformed correctly (only class information is required on a source property). Also, array/collection/class transformations are done implicitly.

There are 4 main methods in this tool (2 inbound + 2 outbound):

```
public static void toBean(Object external, Object bean, Integer... flags);
```
Uses the BeanMapperField annotations on 'bean' to drive the copying of properties from 'external' to 'bean' (both must be beans).
```
public static void toBeanField(Object external, Object bean, Field field, Integer... flags);
```
Similar to toBean() except that only the specified 'field' on 'bean' is set (which doesn't have to be annotated). In this particular case, 'external' can be an array or collection, to map to an array or collection 'field'. The 'field' can be in a superclass of 'bean'.
```
public static void fromBean(Object bean, Object external, Integer... flags);
```
Uses the BeanMapperField annotations on 'bean' to drive the copying of properties from 'bean' to 'external' (both must be beans).
```
public static void fromBeanField(Object bean, Field field, Object external, Integer... flags);
```
Similar to fromBean() except that only the specified 'field' on 'bean' is used (which doesn't have to be annotated) to set a property in 'external'. The 'field' can be in a superclass of 'bean'.

Each method accepts optional extra argument 'flags' which can be set to bitwise or (|) of FLAG_IGNORE_EMPTY_STRING (empty strings treated as if null, ie. not copied) or FLAG_INCLUDE_SUPERCLASS_ANNOTS (also search super-classes for BeanMapperField annotations).

Plus 3 utility methods:

```
public static Object getPropertyValue(Object bean, String propertyPath) throws Exception;
```
Utility method to save writing multiple getters and check for nulls when trying to access a deep object hierarchy. Types agnostic and no object conversions attempted.
```
public static void setPropertyValue(Object value, Class valueClass, Object bean, String propertyPath) throws Exception;
```
Utility method to save writing multiple getters, check for nulls and new's when trying to set a deep object hierarchy. A null 'value' can be set. Types agnostic and no object conversions attempted. However, does use configuration of concrete classes for abstract ones in BeanMapperConfig.xml, for when it has to create intermediate objects.
```
public static Type getPropertyType(Class beanClass, String propertyPath) throws Exception;
```
Utility method to determine the Type of a property in case caller might like to perform their own type checking/conversion.

The 'propertyPath' (equivalent to the 'alias' attribute of the @BeanMapperfield annotation) describes the location of the property in the 'bean' or 'beanClass'.
Performance is excellent. The enclosed JUnit tests can be run in a loop, taking around 30ms for each iteraton, including assertion checking, on a 1.6GHz laptop (debug level WARN).

BeanMapperField annotation

Required on local 'bean' properties to select fields to be mapped by the toBean() or fromBean() methods. Optional when using toBeanField() or fromBeanField() methods. Has optional attribute 'alias'. If 'alias' is not specified then it is assumed that the equivalent property in the 'external' bean has the same name and equivalent object level as the current property. Otherwise, 'alias' can be used to specify a different name and location. Examples:

@BeanMapperField
List<Something> fieldA; // expects property to be called 'fieldA' in 'external' bean

@BeanMapperField(alias="fieldB")
List<Something> fieldA; // expects property to be called 'fieldB' in 'external' bean

@BeanMapperField(alias="subObj1.subObj2[1].fieldC")
List<Something> fieldA; // expects property to be called 'fieldC' in element 1 of array or list subObj2 of subObj1 of 'external' bean

Other optional attributes are 'oneWay' ('in' or 'out') for one way mapping, and 'aliasIn'/'aliasOut' to override 'alias' differently for input/output.
As much as I like annotations, the rest is better covered by implicit type conversion.

Implicit array/collection/class conversions

This works in 2 ways:

At any point, an array can map to a collection and vice-versa. This can be performed to any 'depth', eg. List<List<SomeType>> can map to SomeOtherType[][].
At any point, destination class can be different from source class if a 'converter' has been defined (boxing and unboxing performed by default). The converter will be called to perform the value conversion. Converters must extend BaseConverter and be added to the BeamMapperConfig.xml configuration file (to be found on classpath). The default configuration will convert Calendar, BigInteger, primary types and enums to/from String. Discard or add to these as necessary.

BeanMapperConfig.xml is also used to specify concrete types for abstract ones, eg. if BeanMapper has to create a Calendar or List you can tell it to use GregorianCalendar or ArrayList, or something else.

BeanMapperEventListener interface

A mapped bean can implement this interface to have these lifecycle methods called, to do preparation, housekeeping or manual mappings:

```
public void preInwardMapping(Object source);
```
Called just before inward mapping with toBean*().
```
public void postInwardMapping(Object source);
```
Called just after inward mapping with toBean*().
```
public void preOutwardMapping(Object destination);
```
Called just before outward mapping with fromBean*().

public void postOutwardMapping(Object destination);

Called just after outward mapping with fromBean*().

Debugging mapping issues

Log4j logging at level DEBUG will log field mappings performed.
Log4j logging at level WARN will log mapping failures only (including details of the mapping currently being attempted).
By default, a mapping failure will not throw an exception, terminating processing. However, this can be achieved by setting the system property 'beanmapper.failfast' to 'true'.

Licencing

This software is provided on the basis of the Academic Free Licence (AFL) v3.0 Please note in particular that absolutely no liability is implied. You must also retain attribution statements in the source code.

Any questions or suggestions?

Please contact me directly at phil@activewebsites.co.uk