Package org.modelmapper

Class ModelMapper

java.lang.Object

org.modelmapper.ModelMapper

public class ModelMapper
extends Object

ModelMapper - Performs object mapping, maintains Configuration and stores TypeMaps.

• To perform object mapping use map.
• To configure the mapping of one type to another use createTypeMap.
• To add mappings for specific properties use addMappings supplying a PropertyMap.
• To configure ModelMapper use getConfiguration().
• To validate mappings use validate().

Constructor Summary

Constructors

Constructor	Description
ModelMapper()	Creates a new ModelMapper.

Method Summary

Modifier and Type	Method	Description
<S,D> void	addConverter(Converter<S,D> converter)	Registers the converter to use when mapping instances of types S to D.
<S,D> void	addConverter(Converter<S,D> converter, Class<S> sourceType, Class<D> destinationType)	Registers the converter to use when mapping instances of types S to D.
<S,D> TypeMap<S,D>	addMappings(PropertyMap<S,D> propertyMap)	Adds mappings from the propertyMap into the TypeMap corresponding to source type S and destination type D.
<S,D> TypeMap<S,D>	createTypeMap(Class<S> sourceType, Class<D> destinationType)	Creates a TypeMap for the sourceType and destinationType using the ModelMapper's configuration.
<S,D> TypeMap<S,D>	createTypeMap(Class<S> sourceType, Class<D> destinationType, String typeMapName)	Creates a TypeMap for the sourceType and destinationType identified by the typeMapName using the ModelMapper's configuration.
<S,D> TypeMap<S,D>	createTypeMap(Class<S> sourceType, Class<D> destinationType, String typeMapName, Configuration configuration)	Creates a TypeMap for the sourceType and destinationType identified by the typeMapName using the configuration.
<S,D> TypeMap<S,D>	createTypeMap(Class<S> sourceType, Class<D> destinationType, Configuration configuration)	Creates a TypeMap for the sourceType and destinationType using the configuration.
<S,D> TypeMap<S,D>	createTypeMap(S source, Class<D> destinationType)	Creates a TypeMap for the source's type and destinationType using the ModelMapper's configuration.
<S,D> TypeMap<S,D>	createTypeMap(S source, Class<D> destinationType, String typeMapName)	Creates a TypeMap for the source's type and destinationType identified by the typeMapName using the ModelMapper's configuration.
<S,D> TypeMap<S,D>	createTypeMap(S source, Class<D> destinationType, String typeMapName, Configuration configuration)	Creates a TypeMap for the source's type and destinationType identified by the typeMapName using the configuration.
<S,D> TypeMap<S,D>	createTypeMap(S source, Class<D> destinationType, Configuration configuration)	Creates a TypeMap for the source's type and destinationType using the configuration.
<S,D> TypeMap<S,D>	emptyTypeMap(Class<S> sourceType, Class<D> destinationType)	Creates an empty TypeMap for the sourceType, destinationType.
<S,D> TypeMap<S,D>	emptyTypeMap(Class<S> sourceType, Class<D> destinationType, String typeMapName)	Creates an empty TypeMap for the sourceType, destinationType.
Configuration	getConfiguration()	Returns the ModelMapper's configuration.
<S,D> TypeMap<S,D>	getTypeMap(Class<S> sourceType, Class<D> destinationType)	Returns the TypeMap for the sourceType and destinationType, else returns null if none exists.
<S,D> TypeMap<S,D>	getTypeMap(Class<S> sourceType, Class<D> destinationType, String typeMapName)	Returns the TypeMap for the sourceType, destinationType and typeMapName , else returns null if none exists.
Collection<TypeMap<?,?>>	getTypeMaps()	Returns all TypeMaps for the ModelMapper.
<D> D	map(Object source, Class<D> destinationType)	Maps source to an instance of destinationType.
<D> D	map(Object source, Class<D> destinationType, String typeMapName)	Maps source to an instance of destinationType.
void	map(Object source, Object destination)	Maps source to destination.
void	map(Object source, Object destination, String typeMapName)	Maps source to destination.
<D> D	map(Object source, Type destinationType)	Maps source to an instance of destinationType.
<D> D	map(Object source, Type destinationType, String typeMapName)	Maps source to an instance of destinationType.
ModelMapper	registerModule(Module module)	Register a module
<S,D> TypeMap<S,D>	typeMap(Class<S> sourceType, Class<D> destinationType)	Returns the TypeMap for the sourceType, destinationType, creates TypeMap automatically if none exists.
<S,D> TypeMap<S,D>	typeMap(Class<S> sourceType, Class<D> destinationType, String typeMapName)	Returns the TypeMap for the sourceType, destinationType, and typeMapName creates TypeMap automatically if none exists.
void	validate()	Validates that every top level destination property for each configured TypeMap is mapped to one and only one source property, or that a Converter was set for the TypeMap.

Methods inherited from class java.lang.Object

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

Constructor Detail

ModelMapper

public ModelMapper()

Creates a new ModelMapper.

Method Detail

addConverter

public <S,D> void addConverter(Converter<S,D> converter)

Registers the converter to use when mapping instances of types S to D. The converter will be set against TypeMap corresponding to the converter's type arguments S and D.

Type Parameters:

S - source type

D - destination type

Parameters:

converter - to register

Throws:

IllegalArgumentException - if converter is null or if type arguments S and D are not declared for the converter

See Also:

TypeMap.setConverter(Converter)

addConverter

public <S,D> void addConverter(Converter<S,D> converter,
                                     Class<S> sourceType,
                                     Class<D> destinationType)

Registers the converter to use when mapping instances of types S to D. The converter will be set against TypeMap corresponding to the converter's type arguments S and D.

Type Parameters:

S - source type

D - destination type

Parameters:

converter - to register

Throws:

IllegalArgumentException - if converter is null or if type arguments S and D are not declared for the converter

See Also:

TypeMap.setConverter(Converter)

addMappings

public <S,D> TypeMap<S,D> addMappings(PropertyMap<S,D> propertyMap)

Adds mappings from the propertyMap into the TypeMap corresponding to source type S and destination type D. Explicit mappings defined in the propertyMap will override any implicit mappings for the same properties.

Type Parameters:

S - source type

D - destination type

Parameters:

propertyMap - from which mappings should be loaded

Returns:

TypeMap corresponding to the propertyMap

Throws:

IllegalArgumentException - if propertyMap is null

ConfigurationException - if a configuration error occurs while adding mappings for the propertyMap

createTypeMap

public <S,D> TypeMap<S,D> createTypeMap(Class<S> sourceType,
                                                    Class<D> destinationType)

Creates a TypeMap for the sourceType and destinationType using the ModelMapper's configuration.

Type Parameters:

S - source type

D - destination type

Parameters:

sourceType -

destinationType -

Throws:

IllegalArgumentException - if sourceType or destinationType are null

IllegalStateException - if a TypeMap already exists for sourceType and destinationType

ConfigurationException - if the ModelMapper cannot create the TypeMap

See Also:

getTypeMap(Class, Class)

createTypeMap

public <S,D> TypeMap<S,D> createTypeMap(Class<S> sourceType,
                                                    Class<D> destinationType,
                                                    Configuration configuration)

Creates a TypeMap for the sourceType and destinationType using the configuration.

Type Parameters:

S - source type

D - destination type

Parameters:

sourceType -

destinationType -

configuration - to apply to TypeMap

Throws:

IllegalArgumentException - if sourceType, destinationType or configuration are null

IllegalStateException - if a TypeMap already exists for sourceType and destinationType

ConfigurationException - if the ModelMapper cannot create the TypeMap

See Also:

getTypeMap(Class, Class)

createTypeMap

public <S,D> TypeMap<S,D> createTypeMap(Class<S> sourceType,
                                                    Class<D> destinationType,
                                                    String typeMapName)

Creates a TypeMap for the sourceType and destinationType identified by the typeMapName using the ModelMapper's configuration.

Type Parameters:

S - source type

D - destination type

Parameters:

sourceType -

destinationType -

typeMapName -

Throws:

IllegalArgumentException - if sourceType, destinationType or typeMapName are null

IllegalStateException - if a TypeMap already exists for sourceType, destinationType and typeMapName

ConfigurationException - if the ModelMapper cannot create the TypeMap

See Also:

getTypeMap(Class, Class, String)

createTypeMap

public <S,D> TypeMap<S,D> createTypeMap(Class<S> sourceType,
                                                    Class<D> destinationType,
                                                    String typeMapName,
                                                    Configuration configuration)

Creates a TypeMap for the sourceType and destinationType identified by the typeMapName using the configuration.

Type Parameters:

S - source type

D - destination type

Parameters:

sourceType -

destinationType -

typeMapName -

configuration - to apply to TypeMap

Throws:

IllegalArgumentException - if sourceType, destinationType, typeMapName or configuration are null

IllegalStateException - if a TypeMap already exists for sourceType, destinationType and typeMapName

ConfigurationException - if the ModelMapper cannot create the TypeMap

See Also:

getTypeMap(Class, Class, String)

createTypeMap

public <S,D> TypeMap<S,D> createTypeMap(S source,
                                                    Class<D> destinationType)

Creates a TypeMap for the source's type and destinationType using the ModelMapper's configuration. Useful for creating TypeMaps for generic source data structures.

Type Parameters:

S - source type

D - destination type

Parameters:

source -

destinationType -

Throws:

IllegalArgumentException - if source or destinationType are null

IllegalStateException - if a TypeMap already exists for source's type and destinationType

ConfigurationException - if the ModelMapper cannot create the TypeMap

See Also:

getTypeMap(Class, Class)

createTypeMap

public <S,D> TypeMap<S,D> createTypeMap(S source,
                                                    Class<D> destinationType,
                                                    Configuration configuration)

Creates a TypeMap for the source's type and destinationType using the configuration. Useful for creating TypeMaps for generic source data structures.

Type Parameters:

S - source type

D - destination type

Parameters:

source -

destinationType -

configuration - to apply to TypeMap

Throws:

IllegalArgumentException - if source, destinationType or configuration are null

IllegalStateException - if a TypeMap already exists for source's type and destinationType

ConfigurationException - if the ModelMapper cannot create the TypeMap

See Also:

getTypeMap(Class, Class)

createTypeMap

public <S,D> TypeMap<S,D> createTypeMap(S source,
                                                    Class<D> destinationType,
                                                    String typeMapName)

Creates a TypeMap for the source's type and destinationType identified by the typeMapName using the ModelMapper's configuration. Useful for creating TypeMaps for generic source data structures.

Type Parameters:

S - source type

D - destination type

Parameters:

source -

destinationType -

typeMapName -

Throws:

IllegalArgumentException - if source, destinationType or typeMapName are null

IllegalStateException - if a TypeMap already exists for source's type, destinationType and typeMapName

ConfigurationException - if the ModelMapper cannot create the TypeMap

See Also:

getTypeMap(Class, Class, String)

createTypeMap

public <S,D> TypeMap<S,D> createTypeMap(S source,
                                                    Class<D> destinationType,
                                                    String typeMapName,
                                                    Configuration configuration)

Creates a TypeMap for the source's type and destinationType identified by the typeMapName using the configuration. Useful for creating TypeMaps for generic source data structures.

Type Parameters:

S - source type

D - destination type

Parameters:

source -

destinationType -

typeMapName -

configuration - to apply to TypeMap

Throws:

IllegalArgumentException - if source, destinationType, typeMapName or configuration are null

IllegalStateException - if a TypeMap already exists for source's type, destinationType and typeMapName

ConfigurationException - if the ModelMapper cannot create the TypeMap

See Also:

getTypeMap(Class, Class, String)

getConfiguration

public Configuration getConfiguration()

Returns the ModelMapper's configuration.

getTypeMap

public <S,D> TypeMap<S,D> getTypeMap(Class<S> sourceType,
                                                 Class<D> destinationType)

Returns the TypeMap for the sourceType and destinationType, else returns null if none exists.

Type Parameters:

S - source type

D - destination type

Throws:

IllegalArgumentException - is sourceType or destinationType are null

See Also:

createTypeMap(Class, Class)

getTypeMap

public <S,D> TypeMap<S,D> getTypeMap(Class<S> sourceType,
                                                 Class<D> destinationType,
                                                 String typeMapName)

Returns the TypeMap for the sourceType, destinationType and typeMapName , else returns null if none exists.

Type Parameters:

S - source type

D - destination type

Throws:

IllegalArgumentException - is sourceType, destinationType or typeMapName are null

See Also:

createTypeMap(Class, Class, String)

typeMap

public <S,D> TypeMap<S,D> typeMap(Class<S> sourceType,
                                              Class<D> destinationType)

Returns the TypeMap for the sourceType, destinationType, creates TypeMap automatically if none exists.

Type Parameters:

S - source type

D - destination type

Throws:

IllegalArgumentException - is sourceType, destinationType are null

typeMap

public <S,D> TypeMap<S,D> typeMap(Class<S> sourceType,
                                              Class<D> destinationType,
                                              String typeMapName)

Returns the TypeMap for the sourceType, destinationType, and typeMapName creates TypeMap automatically if none exists.

Type Parameters:

S - source type

D - destination type

Throws:

IllegalArgumentException - is sourceType, destinationType or typeMapName are null

emptyTypeMap

public <S,D> TypeMap<S,D> emptyTypeMap(Class<S> sourceType,
                                                   Class<D> destinationType)

Creates an empty TypeMap for the sourceType, destinationType.

Type Parameters:

S - source type

D - destination type

Throws:

IllegalArgumentException - is sourceType or destinationType are null, or TypeMap<SourceType, DestinationType already defined in the TypeMapStore

emptyTypeMap

public <S,D> TypeMap<S,D> emptyTypeMap(Class<S> sourceType,
                                                   Class<D> destinationType,
                                                   String typeMapName)

Creates an empty TypeMap for the sourceType, destinationType.

Type Parameters:

S - source type

D - destination type

Throws:

IllegalArgumentException - is sourceType or destinationType are null, or TypeMap<Source Type, DestinationType already defined in the TypeMapStore

getTypeMaps

public Collection<TypeMap<?,?>> getTypeMaps()

Returns all TypeMaps for the ModelMapper.

map

public <D> D map(Object source,
                 Class<D> destinationType)

Maps source to an instance of destinationType. Mapping is performed according to the corresponding TypeMap. If no TypeMap exists for source.getClass() and destinationType then one is created.

Type Parameters:

D - destination type

Parameters:

source - object to map from

destinationType - type to map to

Returns:

fully mapped instance of destinationType

Throws:

IllegalArgumentException - if source or destinationType are null

ConfigurationException - if the ModelMapper cannot find or create a TypeMap for the arguments

MappingException - if a runtime error occurs while mapping

map

public <D> D map(Object source,
                 Class<D> destinationType,
                 String typeMapName)

Maps source to an instance of destinationType. Mapping is performed according to the corresponding TypeMap for the typeMapName. If no TypeMap exists for the source.getClass(), destinationType and typeMapName then one is created.

Type Parameters:

D - destination type

Parameters:

source - object to map from

destinationType - type to map to

typeMapName - name of existing TypeMap to use mappings from

Returns:

fully mapped instance of destinationType

Throws:

IllegalArgumentException - if source, destinationType or typeMapName are null

ConfigurationException - if the ModelMapper cannot find or create a TypeMap for the arguments

MappingException - if a runtime error occurs while mapping

map

public void map(Object source,
                Object destination)

Maps source to destination. Mapping is performed according to the corresponding TypeMap. If no TypeMap exists for source.getClass() and destination.getClass() then one is created.

Parameters:

source - object to map from

destination - object to map to

Throws:

IllegalArgumentException - if source or destination are null

ConfigurationException - if the ModelMapper cannot find or create a TypeMap for the arguments

MappingException - if an error occurs while mapping

map

public void map(Object source,
                Object destination,
                String typeMapName)

Maps source to destination. Mapping is performed according to the corresponding TypeMap for the typeMapName. If no TypeMap exists for the source.getClass(), destination.getClass() and typeMapName then one is created.

Parameters:

source - object to map from

destination - object to map to

typeMapName - name of existing TypeMap to use mappings from

Throws:

IllegalArgumentException - if source, destination or typeMapName are null

ConfigurationException - if the ModelMapper cannot find or create a TypeMap for the arguments

MappingException - if an error occurs while mapping

map

public <D> D map(Object source,
                 Type destinationType)

Maps source to an instance of destinationType. Mapping is performed according to the corresponding TypeMap. If no TypeMap exists for source.getClass() and destinationType then one is created.

To map a parameterized destination type, subclass TypeToken and obtain its Type:

 Type listType = new TypeToken<List<String>>() {}.getType();
 List<String> strings = modelMapper.map(source, listType);
 

Type Parameters:

D - destination type

Parameters:

source - object to map from

destinationType - type to map to

Returns:

fully mapped instance of destinationType

Throws:

IllegalArgumentException - if source or destinationType are null

ConfigurationException - if the ModelMapper cannot find or create the TypeMap

MappingException - if a runtime error occurs while mapping

map

public <D> D map(Object source,
                 Type destinationType,
                 String typeMapName)

Maps source to an instance of destinationType. Mapping is performed according to the corresponding TypeMap for the typeMapName. If no TypeMap exists for the source.getClass(), destination.getClass() and typeMapName then one is created.

To map a parameterized destination type, subclass TypeToken and obtain its Type:

 Type listType = new TypeToken<List<String>>() {}.getType();
 List<String> strings = modelMapper.map(source, listType, "string-list");
 

Type Parameters:

D - destination type

Parameters:

source - object to map from

destinationType - type to map to

typeMapName - name of existing TypeMap to use mappings from

Returns:

fully mapped instance of destinationType

Throws:

IllegalArgumentException - if source, destinationType or typeMapName are null

ConfigurationException - if the ModelMapper cannot find or create the TypeMap

MappingException - if a runtime error occurs while mapping

validate

public void validate()

Validates that every top level destination property for each configured TypeMap is mapped to one and only one source property, or that a Converter was set for the TypeMap. If not, a ConfigurationException is thrown detailing any missing mappings.

Throws:

ValidationException - if any TypeMaps contain unmapped properties

registerModule

public ModelMapper registerModule(Module module)

Register a module

Parameters:

module - a module for extension