org.osgl.util

Class DataMapper

java.lang.Object

org.osgl.util.DataMapper

public class DataMapper
extends Object

Map data from one structure into another structure. The target data structure must be exists and must be mutable to do the data mapping.

Error reporting

DataMapper consumer can dictate on how DataMapper to handle exceptions by passing boolean value ignoreError to constructor.

If ignoreError is set to true then DataMapper will not raise error for any exception raised during mapping process. It will simply skip to the next field.

Otherwise it will raise MappingException when

• Exceptions raised
• Type conversion failed

Mapping rule

Three mapping rule has been defined:

• DataMapper.MappingRule.STRICT_MATCHING
• mapping happens between exact same name, and do type conversion if needed
• DataMapper.MappingRule.KEYWORD_MATCHING
• mapping happens if the Keyword of source field name and target field name matches. For example foo_bar can be mapped to fooBar.

Field name based mapping

DataMapper do field name based mapping, in other words, it does not rely on JavaBean properties to do the mapping. For example if source object has a field name foo, the value of source.foo will be mapped to the target object’s field foo: target.foo.

Recursive mapping

DataMapper do recursive mapping. If target object has embedded structure and source object has the corresponding value, then that value will be mapped to target object’s embedded structure recursively.

Type conversion

When mapping semantic is DataMapper.Semantic.MAP, the mapper will try to convert from source type to target type when types doesn’t match. Otherwise it will raise an MappingException.

Mapping to array

For target field that is an array, tt will first try to do type conversion in case special converter has been defined.

If there is not converter defined or when root mapping target is an array, then it will check if source component can be converted to an Iterable. If it’s okay then it will add elements from the iterable to the target array. In case element exists in the target array then it will do recursive mapping from the source element to the target element.

Handle out of range

If source array/collection has more elements that the target array can hold, an new array will be returned when calling to getTarget().

If array is inner property of another structure, it will be replaced with the new array that holds all elements from source array/collection

Mapping to a List

Determine the list element type. If this is a recursive mapping, list element type can be found from the field type of upper level target. Otherwise, it will try to determine list type from the existing elements of the list. If there is no element in the list then it assume list can be put in any type of object.

For target field that is an list, it will first try to do type conversion in case special converter has been defined.

If there is no converter defined, then it will check if source component can be converted to an Iterable. If it’s okay then it will add elements from the iterable to the target list. In case the element in the position is not null in the target list, it will do recursive mapping from the source element to the target element.

If source array/collection has more elements than the target list, then the extra elements will be added to the list

Mapping to a Set

Determine the set element type. If this is a recursive mapping, set element type can be found from the field type of upper level target. Otherwise, it will try to determine list type from the existing elements of the set. If there is no element in the list then it assume set can be put in any type of object.

For target field that is a set, it will first try to do type conversion in case special converter has been defined.

If there is no converter defined, then it will check if source component can be converted to an Iterable. If it’s okay then it will add elements from the iterable to the target set. Unlike mapping to an array or a list, there is no recursive element mapping happening for set, it just add the elements from source iterable into the target set, after type conversion if needed.

Mapping to a Map

When mapping to a map, it will check if target map has existing non-null value for a certain property, if it exists, then it will do recursive mapping from property value to the target map entry value.

If there are extra properties in the source object, they will be added into the target map if the type can be converted.

When mapping to a map, the DataMapper.MappingRule.KEYWORD_MATCHING won’t effect, it is treated as DataMapper.MappingRule.STRICT_MATCHING

Mapping from a Map

Again it will try to do type conversion to allow custom data mapping for certain types happening. In case no type conversion is done then

It treats map entry as fields of a class, literally the entry is treated as the field name and entry value is treated as field value. And then start from there to do the data mapping process.

null value

If null value encountered in source, the corresponding field/map entry will be set to null in the target.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DataMapper.MappingRule
static class	DataMapper.Semantic The mapping semantic steering the mapping logic

Constructor Summary

Constructors

Constructor and Description

DataMapper(Object source, Object target, ParameterizedType targetGenericType, DataMapper.MappingRule rule, DataMapper.Semantic semantic, String filterSpec, boolean ignoreError, boolean ignoreGlobalFilter, Lang.Function keyTransformer, Map<Class,Object> conversionHints, Lang.Function<Class,?> instanceFactory, TypeConverterRegistry typeConverterRegistry, Class<?> rootClass, Map<String,String> specialMapping)

Method Summary

Modifier and Type	Method and Description
Object	getTarget()
static Lang.Function	keyTransformer(Keyword.Style targetStyle)

Methods inherited from class java.lang.Object

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

Constructor Detail

DataMapper

public DataMapper(Object source,
                  Object target,
                  ParameterizedType targetGenericType,
                  DataMapper.MappingRule rule,
                  DataMapper.Semantic semantic,
                  String filterSpec,
                  boolean ignoreError,
                  boolean ignoreGlobalFilter,
                  Lang.Function keyTransformer,
                  Map<Class,Object> conversionHints,
                  Lang.Function<Class,?> instanceFactory,
                  TypeConverterRegistry typeConverterRegistry,
                  Class<?> rootClass,
                  Map<String,String> specialMapping)

Method Detail

getTarget

public Object getTarget()

keyTransformer

public static Lang.Function keyTransformer(Keyword.Style targetStyle)