Basic Mapping

As mentioned in the overview, there are three types of configurations: Annotations, XML and API.
The basic mapping is represented in Annotation with @JMap, in XML with the node <attribute> and in API with Attribute class.
These give the same possibility and use the same parameters but in different format.
Follows the explanation in detail of what the basic mapping offers.

The class used as an example is the following:

class MyClass {

    private String field;

    // getter and setter..

}

#Value

the parameter value permits to define the target field name.

Annotation

Value is the default parameter for the annotation that you may omit to write, if used alone.

class MyClass {

   @JMap("targetFieldName") // or @JMap(value = "targetFieldName")
   private String field;
   
}

XML

The XSD has not been added in order to improve readability.
For more information see XSD wiki page.

The equivalent configuration in xml is:

<jmapper>
   <class name="package.MyClass">
      <attribute name="field">
         <value name="targetFieldName"/>
      </attribute>
   </class>
</jmapper>

The root node jmapper must contain one or more class nodes, the class node may contain one or more attribute nodes.

API

The configuration via API has the same structure of the configuration in XML.
It is suggested to make the import of the static methods.

...
import static com.googlecode.jmapper.api.JMapperAPI.*;
...

JMapperAPI jmapperAPI = new JMapperAPI()
    .add(mappedClass(MyClass.class)
             .add(attribute("field")
                     .value("targetFieldName")));

Attributes

With the attributes parameter it's possible define more target fields.
This is useful when you want associate a field with many other that belong to different classes.
This configuration may lead to undesirable results in the case there are multiple matches between the identifiers declared in attributes and the fields of the target class, in this case JMapper considers valid the first field that respects the correspondence.
This use is recommended only if you are certain of the uniqueness of the identifiers defined.

Annotation

class MyClass {

   @JMap(attributes = {"firstField","secondField"})
   private String field;
   
}

To better understand how attributes parameter works see the following example:

class Destination {          class Source {

   String dField3;              @JMap(attributes={"dField1","dField2","dField3"})
   String dField2;              String sField1;
   String dField1;

   //getters and setters..      //getter and setter..
}                            }

Code:

Source source = new Source("sField1");

JMapper mapper = new JMapper(Destination.class, Source.class);

Destination destination = mapper.getDestination(source);

Output:

Destination[dField3=null, dField2=null, dField1="sField1"]

The first field of Destination that respects the correspondence is dField1.

XML

The equivalent configuration in xml is:

<jmapper>
   <class name="package.Source">
      <attribute name="sField1">
         <attributes>
             <attribute name="dField1"/>
             <attribute name="dField2"/>
             <attribute name="dField3"/>
         </attributes>
      </attribute>
   </class>
</jmapper>

API

The equivalent configuration with API is:

...
import static com.googlecode.jmapper.api.JMapperAPI.*;
...

JMapperAPI jmapperAPI = new JMapperAPI()
    .add(mappedClass(Source.class)
             .add(attribute("sField1")
                     .targetAttributes("dField1", "dField2", "dField3")));

Classes

Classes is used to limit the association to a defined set of classes, without value and attributes, you indicates to JMapper that the identifier of target field is the same of mapped field.

Annotation

class MyClass {

   @JMap(classes = {Target1.class, Target2.class, Target3.class})
   private String field;

}

For example, we have the following classes:

   class Target4 {             class MyClass{

                                   @JMap(classes={Target1.class, Target2.class, Target3.class})
       String field;               String field;

       // getter and setter..      // getter and setter.. 
   }                           }

Code:

new JMapper<Target4, MyClass>(Target4.class, MyClass.class);

Output:

"JMapper AbsentRelationshipException: there isn't relationship between Target4 Class and Source Class"

XML

The equivalent configuration in xml is:

<jmapper>
   <class name="package.MyClass">
      <attribute name="field">
         <classes>
             <class name="package.Target1"/>
             <class name="package.Target2"/>
             <class name="package.Target3"/>
         </classes>
      </attribute>
   </class>
</jmapper>

API

The equivalent configuration with API is:

...
import static com.googlecode.jmapper.api.JMapperAPI.*;
...

JMapperAPI jmapperAPI = new JMapperAPI()
    .add(mappedClass(MyClass.class)
             .add(attribute("sField1")
                     .targetClasses(Target1.class, Target2.class, Target3.class)));

Value and Classes

This combination allows you to limit the association between the mapped field and the target field to a defined set of classes, declaring the target field name.

Annotation

class MyClass {

   @JMap(value = "targetField", classes = {Target1.class, Target2.class, Target3.class})
   private String field;

}

XML

The equivalent configuration in xml is:

<jmapper>
   <class name="package.MyClass">
      <attribute name="field">
         <value name="targetField"/>
         <classes>
             <class name="package.Target1"/>
             <class name="package.Target2"/>
             <class name="package.Target3"/>
         </classes>
      </attribute>
   </class>
</jmapper>

API

The equivalent configuration with API is:

...
import static com.googlecode.jmapper.api.JMapperAPI.*;
...

JMapperAPI jmapperAPI = new JMapperAPI()
    .add(mappedClass(MyClass.class)
             .add(attribute("field")
                     .value("targetField")
                     .targetClasses(Target1.class, Target2.class, Target3.class)));

Attributes and Classes

To clarify the association between the mapped field and other fields belonging to different classes, you can simply make a joint use of attributes and classes.

Annotation

class MyClass {

   @JMap(attributes = {"field1","field2","field3"}, 
            classes = {Target1.class, Target2.class, Target3.class})
   private String field;

}

In this specific example JMapper recognizes the association that exists between the mapped field with the field "field1" of the Source class, with the field "field2" of the Source2 class and with the field "field3" of the Source3 class.
The equality of the mapped field and the target field can be specified with an empty string "". For example:

@JMap(attributes = {"field1", "", "field3"}
         classes = {Target1.class, Target2.class, Target3.class})

XML

The equivalent configuration in xml is:

<jmapper>
   <class name="package.MyClass">
      <attribute name="field">
         <attributes>
             <attribute name="field1"/>
             <attribute name="field2"/>
             <attribute name="field3"/>
         </attributes>
         <classes>
             <class name="package.Target1"/>
             <class name="package.Target2"/>
             <class name="package.Target3"/>
         </classes>
      </attribute>
   </class>
</jmapper>

API

The equivalent configuration with API is:

...
import static com.googlecode.jmapper.api.JMapperAPI.*;
...

JMapperAPI jmapperAPI = new JMapperAPI()
    .add(mappedClass(MyClass.class)
             .add(attribute("field")
                     .targetAttributes("field1", "field2", "field3")
                     .targetClasses(Target1.class, Target2.class, Target3.class)));