Class ModelMapper

java.lang.Object
org.modelmapper.ModelMapper

public class ModelMapper extends Object
ModelMapper - Performs object mapping, maintains Configuration and stores TypeMaps.
  • Constructor Summary

    Constructors
    Constructor
    Description
    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.
    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.
    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.
    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
    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 Details

    • ModelMapper

      public ModelMapper()
      Creates a new ModelMapper.
  • Method Details

    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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