Global Mapping

In some cases we have the need to map two or more fields toward the same field.
Currently the only mode to do this is configure each field creating much redundance.
To avoid it, will be introduced the global mapping.

All configuration types share the same parameters and are:

• value, it permits to define the target field name
  
• classes, are the classes to which the field must belong
  
• attributes,are the fields of the current class that will be part of the mapping
  
• excluded, are the fields of the current class that will be excluded from mapping

##Annotation

The annotation to use is @JGlobalMap and must be applied to the class, it has the parameters:

#####1° example

With @JMap:

class Bean {
           
   @JMap("properties") 
   String field1;
   
   @JMap("properties")
   String field2;

   String field3;
               
  //getters and setters..
}

With @JGlobalMap:

@JGlobalMap(value="properties",excluded={"field3"})
// in alternative
// @JGlobalMap(value="properties",attributes={"field1","field2"})
class Bean {
           
   String field1;
   String field2;
   String field3;
            
   //getters and setters..
}

####2° example

With @JMap:

class Bean {
           
   @JMap 
   String field1;
   
   @JMap 
   String field2;
   
   String field3;
               
   //getters and setters..
}

With @JGlobalMap:

@JGlobalMap(excluded={"field3"})
// in alternative 
// @JGlobalMap(attributes={"field1""field2"})
class Bean {
           
    String field1;
    String field2;
    String field3;

    //getters and setters..
}

In this case the mapping isn't toward one field, but each field is mapped toward a field with his name.

@JGlobalMap has greater visibility of @JMap, if a field is not configured with @JGlobalMap JMapper checks if it is configured with @JMap.

For example:

@JGlobalMap(excluded={"field3"})
class Bean {
           
    String field1;

    String field2;

    @JMap("other")
    String field3;
               
    //getters and setters..
}

In this case field3 is included in the mapping.

##XML

The tag to use is:<global>.
Considering the class wrote earlier and see the following examples.

#####1° example

The local fields have the same target field names.

With <attribute>:

<jmapper>
   <class name = "Bean">
      <attribute name = "field1">
         <value name = "field1"/>
      </attribute>
      <attribute name = "field2">
         <value name = "field2"/>
      </attribute>
   </class>
</jmapper>

With <global>:

<jmapper>
   <class name = "Bean">
      <global>
         <excluded>
            <attribute name = "field3"/>
         </excluded>
      <!-- or 
         <attributes>
            <attribute name = "field1"/>
            <attribute name = "field2"/>
         </attributes>
      -->
      </global>
   </class>
</jmapper>

####2° example

Explicit target field.

With <attribute>:

<jmapper>
   <class name = "Bean">
      <attribute name = "field1">
         <value name = "properties"/>
      </attribute>
      <attribute name = "field2">
         <value name = "properties"/>
      </attribute>
   </class>
</jmapper>

With <global>:

<jmapper>
   <class name = "Bean">
      <global>
         <value name = "properties"/>
         <excluded>
            <attribute name = "field3"/>
         </excluded>
      <!-- or 
         <attributes>
            <attribute name = "field1"/>
            <attribute name = "field2"/>
         </attributes>
      -->
      </global>
   </class>
</jmapper>

<global> has greater visibility of <attribute>, if a field is not configured with <global> JMapper checks if it is configured with <attribute>.
For example:

<jmapper>
   <class name = "Bean">
      <global>
         <value name = "properties"/>
            <excluded>
               <attribute name = "field3" />
  	    </excluded>
      </global>
      <attribute name = "field3">
         <value name = "other"/>
      </attribute>
   </class>
</jmapper>

##API The relative version of API uses the Global class under the com.googlecode.jmapper.api package.
It's suggested to import static methods to increase readability of configuration, as shown in the following example.

####1° Example The local fields have the same target field names.
With Attribute:

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

new JMapperAPI()
   .add(mappedClass(Destination.class)
      .add(attribute("field1")
             .value("field1"))
      .add(attribute("field2")
             .value("field2")));

With Global:

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

new JMapperAPI()
   .add(mappedClass(Destination.class)
      .add(global()
             .excludedAttributes("other")));
      // in alternative 
      //     .includedAttributes("field1", "field2")));

####2° Example Explicit target field.
With Attribute:

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

new JMapperAPI()
   .add(mappedClass(Destination.class)
      .add(attribute("field1")
             .value("properties"))
      .add(attribute("field2")
             .value("properties")));

With Global:

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

new JMapperAPI()
   .add(mappedClass(Destination.class)
      .add(global()
             .value("properties")
             .excludedAttributes("other")));
      // in alternative 
      //     .includedAttributes("field1", "field2")));