Home

This wiki is under construction

The mapping is a mechanical operation almost 100%, in medium-large applications, between development, testing and bug fixing, it reaches a weight that is certainly not negligible.

As the rule may seem elementary, enclose in a single framework a potentially unlimited number of combinations, recursive mapping, addition of logic and other features, makes its implementation very complex with questionable compromises, such as poor performance, covering a limited features, etc... .

JMapper aims not only to coverage all requirements but also to make it as easy as possible to use, that's all with performance equivalent or higher to handwritten code.

JMapper allows:

• to create and enrich target objects
• to apply a specific logic to the mapping
• to perform complex mapping (Collection, Map, Array, inner classes, etc...)
• to perform recursive mapping (mapped objects into other objects)
• to manage implicit and explicitrelationships of various types:
  

• one to one
  
• one to many
  
• many to one
  

to implement explicit conversions

to configure the mapping using the annotation and / or xml

to apply inherited configurations

to write quick and simple xml configuration file, through a series of utility methods

Preface

Before describing the features of the framework is good to do a little introduction: the Destination is the instance that captures the data, the Source is the instance that contains the data, the goal is to get the Destination starting from the Source.
The configurations are associated with the instance variables and may be present in the Destination and Source, then we will call target field the target field of the configuration and mapped field the field that contains the configuration.
As a prerequisite classes used for mapping must comply with the Javabean conventions.

Since 1.3.0 version it's possible define get and set custom methods.
For more info go to wiki page.

Below shows the classes that will be used in the following examples:

class Destination{                      class Source{

    private String id;                      private String id;
    private String destinationField;        private String sourceField;
    private String other;                   private String other;

    // getters and setters...               // getters and setters...
}                                       }

As mentioned in the introduction, JMapper allows you to configure the mapping using both annotations and XML. In the next chapter we will learn to configure classes with annotation and especially with @JMap.

IMPORTANT! the XML configuration has greater visibility of the equivalent annotation

Annotated configuration

The annotation used to configure the single field is @JMap, it has several parameters, including: value.
Value is the default parameter of the annotations and therefore isn't necessary to explain it if used individually.

class Destination{                      
    
    /* implicit mapping when mapped field name and target field name match */
    @JMap 
    private String id;                      
    /* explicit mapping when mapped field name and target field name don't match */
    @JMap("sourceField") 
    private String destinationField;       
    private String other;                  

    // getters and setters...                
}                                     

XML configuration

this is the xml configuration equivalent to the previous one written with annotation:

<jmapper>
  <class name="it.jmapper.bean.Destination">
    <attribute name="id">
      <value name="id"/>
    </attribute>
    <attribute name="destinationField">
      <value name="sourceField">
    </attribute>
  </class>
</jmapper>

For writing automated XML, read the XML handling section.

Example

Once set up, we go immediately to a practical example:

Source source = new Source("id", "sourceField", "other");

JMapper <Destination, Souce> jmapper = new JMapper <>(Destination.class, Source.class);

Destination destination = jmapper.getDestination(source);

System.out.println(destination);

The class to use is JMapper, takes as input two classes: the first from the left, belonging to the Destination and the second to Source, then just invoke the method getDestination passing an instance of Source to create an instance of Destination.
The output below shows the fields of the destination bean.

Destination [id="id", destinationField="source field", other=null]

IMPORTANT! the configuration can be written in both classes, the result is the same

JMapper constructors

If both classes are configured, the framework will consider the configuration of the Destination Class. If you want to define which configuration to be analyze, simply pass to the constructor the ChooseConfig enumeration.

new JMapper <Destination, Source>(Destination.class, Source.class, ChooseConfig.SOURCE);

ChooseConfig.SOURCE	it evaluates the configuration of Source
ChooseConfig.DESTINATION	it evaluates the configuration of Destination

if you wrote the xml, you have to pass the path to the constructor, as below:

new JMapper <Destination, Source>(Destination.class, Source.class, "xml/jmapper.xml");

Remember the xml file must be accessible from your classpath at runtime. If you want define an external path, you need to add this prefix: file: for example:
Windows "file:/C:/path/jmapper.xml"
Unix "file:/Users/path/jmapper.xml"

Below the constructor complete with all parameters:

new JMapper <Destination, Source>(Destination.class, Source.class, ChooseConfig.SOURCE, "xml/jmapper.xml");