General Usage

Requirements for running Dozer:

  • Dozer uses Jakarta Commons Logging.
  • Dozer needs a few thirdparty runtime jars.
  • All of the required runtime jars are in the {dozer.home}/repository directory and need to be in your Classpath
  • The dozer.jar file in the {dozer.home}/dist directory needs to be in your Classpath

    • Dozer Bean Mapper

    Before we go over setting up custom xml bean mappings, let us look at how simple it is to use Dozer. The Dozer mapping implementation has a method called map which takes a source object and either a destination object or destination object class type. After mapping the two objects it then returns the destination object with all of its mapped fields. 
                      
MapperIF mapper = new DozerBeanMapper();

DestinationObject destObject =
  (DestinationObject) mapper.map(sourceObject, DestinationObject.class);
             or
DestinationObject destObject = new DestinationObject();
mapper.map(sourceObject, destObject);
    IMPORTANT: For real-world applications it is not recommended that you create a new instance of the Mapper each time you map objects. Typically a system will only have one DozerBeanMapper instance per VM. If you are not using an IOC framework where you can define the MapperIF as singleton="true", a DozerBeanMapperSingletonWrapper convenience class has been provided in the Dozer jar.

    Injecting Custom Mapping Files

    The Dozer mapping xml file(s) define any custom mappings that can't be automatically performed by the Dozer mapping engine. Any custom Dozer mapping files need to be injected into the Mapper implementation(net.sf.dozer.util.mapping.DozerBeanMapper). Both setter-based and constructor-based injection are supported.

    Preferably, you will be using an IOC framework such as Spring for these Dozer injection requirements. Alternatively, the injection of mapping files can be done programatically. Below is a programmatic approach to creating a bean mapper. Note that this is NOT the recommended way to retrieve the bean mapper . Each new instance needs to be initialized and this consumes time as well as resources. If you are using the mapper this way just wrap it using the singleton pattern. 

                 
List myMappingFiles = new ArrayList();
myMappingFiles.add("dozerBeanMapping.xml");
myMappingFiles.add("someOtherDozerBeanMappings.xml");
DozerBeanMapper mapper = new DozerBeanMapper();
mapper.setMappingFiles(myMappingFiles);
DestinationObject destObject = (DestinationObject) mapper.map(sourceObject, DestinationObject.class);
    IMPORTANT: Mapper instance(s) should be setup as a Singleton regardless of how you choose to inject the Mapper instance(s). You should configure the Mapper this way so that you do not have to reload and reinitialize the mapping files for each individual mapping during the lifecycle of your app. Reinitializing the mapping files for each mapping would be inefficent and unnecessary. The DozerBeanMapper.java class is thread safe.

    Spring Integration

    The following is an example how the Mapper bean would be configured via Spring.

    Sample spring.xml bean definition... 

                 
<bean id="net.sf.dozer.util.mapping.MapperIF" 
  class="net.sf.dozer.util.mapping.DozerBeanMapper" singleton="true">
  <property name="mappingFiles">
    <list>
      <value>dozer-global-configuration.xml</value>			   
      <value>dozer-bean-mappings.xml</value>
      <value>more-dozer-bean-mappings.xml</value>
    </list>
  </property>
</bean>


    Dozer Bean Mapper Singleton Wrapper

    There is one way to configure the DozerBeanMapperSingletonWrapper to use your custom mapping file.

    • Using one mapping file: A file called dozerBeanMapping.xml file will be loaded if it is in your Classpath. You can find a sample of this file in the {dozer.home}/mappings directory.

    The mapping file defines all of the relationships between Java classes and their attributes. The Custom Mappings section details the custom XML mapping options that are available.

    The following example show how to use the DozerBeanMapperSingletonWrapper. Dozer has a method called map which takes a source object and either a destination object or destination object class type. After mapping the two objects it then returns the destination object with all of its mapped fields. 

              MapperIF mapper = DozerBeanMapperSingletonWrapper.getInstance(); DestinationObject destObject =
          (DestinationObject) mapper.map(sourceObject, DestinationObject.class);

          or

          MapperIF mapper = DozerBeanMapperSingletonWrapper.getInstance(); DestinationObject destObject = new
          DestinationObject(); mapper.map(sourceObject, destObject);