Configuration via XML

The majority of Dozer’s behaviour can be configured from within XML mapping files. Settings can appear inside five different scopes which affect the elements they are applied to: Global, per class mapping, at individual class level, per field mapping, and at individual field level.

Configuration Scopes

Global Scope

The configuration block is used to set the global default settings. Also, any Custom Converters are defined in this section. The configuration block is entirely "optional".

Dozer supports the ability to have multiple mapping files. Each of these mapping files can have their own configuration block. A mapping will inherit its configuration from the mapping file that it is stored in. Implicit mappings will inherit the default values for configuration.

The following is the sample configuration block from the example mappings file:

<configuration>
    <date-format>MM/dd/yyyy HH:mm</date-format>
    <stop-on-errors>true</stop-on-errors>
    <wildcard>true</wildcard>
    <custom-converters>
        <!-- these are always bi-directional -->
        <converter type="com.github.dozermapper.core.converters.TestCustomConverter">
            <class-a>com.github.dozermapper.core.vo.TestCustomConverterObject</class-a>
            <class-b>another.type.to.Associate</class-b>
        </converter>
    </custom-converters>
</configuration>

All global settings appear as separate XML tags containing their value.

Per Class Mapping

Global settings (or their defaults) can be overridden at the individual mapping level. Here, configuration values are set using name="value" attributes. They will affect all mapping operations between the two classes.

<mapping wildcard="false" date-format="MM/dd/yyyy HH:mm">
    <class-a>com.github.dozermapper.core.vo.SpringBean</class-a>
    <class-b>com.github.dozermapper.core.vo.SpringBeanPrime</class-b>
    <field>
        <a>anAttributeToMap</a>
        <b>anAttributeToMapPrime</b>
    </field>
</mapping>

At Individual Class Level

Sometimes, you may want to apply a setting only to one of the two classes. This can be achieved by placing the attribute inside the class-a or class-b tag:

<mapping>
    <class-a is-accessible="true">com.github.dozermapper.core.vo.SpringBean</class-a>
    <class-b>com.github.dozermapper.core.vo.SpringBeanPrime</class-b>
    <field>
        <a>anAttributeToMap</a>
        <b>anAttributeToMapPrime</b>
    </field>
</mapping>

Per Field Mapping

Likewise, you can change the mapping behaviour for specific field pairs:

<mapping>
    <class-a>com.github.dozermapper.core.vo.SpringBean</class-a>
    <class-b>com.github.dozermapper.core.vo.SpringBeanPrime</class-b>
    <field remove-orphans="false">
        <a>anAttributeToMap</a>
        <b>anAttributeToMapPrime</b>
    </field>
</mapping>

At Individual Field Level

Finally, some settings can be applied to a single field:

<mapping>
    <class-a>com.github.dozermapper.core.vo.SpringBean</class-a>
    <class-b>com.github.dozermapper.core.vo.SpringBeanPrime</class-b>
    <field>
        <a get-method="getTheAttribute">anAttributeToMap</a>
        <b>anAttributeToMapPrime</b>
    </field>
</mapping>

Available Configuration Settings

The following table lists the available configuration options and mapping directives, in which scopes they can appear, and the section of the manual containing more information:

Name	Global	Class Mapping	Single Class	Field Mapping	Single Field	Manual Section
allowed-exceptions	X					see below
custom-converter				X		Custom Converters
custom-converter-id				X		Custom Converters
custom-converter-param				X		Custom Converters
copy-by-reference				X		Copy By Reference
copy-by-references	X					Copy By Reference
create-method			X		X	Custom Create Method
bean-factory	X	X	X			Custom Bean Factories
date-format	X	X			X	String to Date Mapping
factory-bean-id			X			Custom Bean Factories
get-method					X	Custom Methods
is-accessible			X		X	Mapping immutable types
key					X	Map Mapping
map-empty-string	X	X	X			Excluding Fields
map-id		X				Context Based Mapping
map-null	X	X	X			Excluding Fields
map-set-method			X		X	Map Mapping
map-get-method			X		X	Map Mapping
relationship-type	X	X		X		Collection Mapping
remove-orphans				X		Collection Mapping
set-method					X	Custom Methods
skip-constructor			X			Mapping immutable types
stop-on-errors	X					see below
trim-strings	X	X				see below
type		X		X		One-Way Mapping
variables	X					Expression Language
wildcard	X	X				see below
wildcard-case-insensitive	X	X				see below

Name

Global

Class Mapping

Single Class

Field Mapping

Single Field

Manual Section

allowed-exceptions

see below

custom-converter

Custom Converters

custom-converter-id

Custom Converters

custom-converter-param

copy-by-reference

copy-by-references

create-method

bean-factory

Custom Bean Factories

date-format

String to Date Mapping

factory-bean-id

Custom Bean Factories

get-method

Custom Methods

is-accessible

Mapping immutable types

key

Map Mapping

map-empty-string

Excluding Fields

map-id

Context Based Mapping

map-null

map-set-method

map-get-method

relationship-type

remove-orphans

set-method

skip-constructor

Mapping immutable types

stop-on-errors

see below

trim-strings

see below

type

One-Way Mapping

variables

Expression Language

wildcard

see below

wildcard-case-insensitive

see below

Error handling (stop-on-errors, allowed-exceptions)

By default, if Dozer encounters an error while performing a field mapping, an exception is thrown and the mapping aborted. While this is the recommended behaviour, Dozer can be instructed to ignore the error and simply continue with the next field, via the stop-on-errors policy.

You can also specify exceptions that should cause Dozer to stop and rethrow them, even if stop-on-errors is set to false, using the allowed-exceptions element:

<configuration>
    <stop-on-errors>false</stop-on-errors>
    <allowed-exceptions>
        <exception>org.example.UnrecoverableError</exception>
        <exception>org.example.BadException</exception>
    </allowed-exceptions>
</configuration>

Trimming Strings (trim-strings)

As the name suggests, trim-strings applies Java’s String.trim() to the source value before calling the target beans’s setter.

Wildcard mapping (wildcard, wildcard-case-insensitive)

Per default, Dozer maps all fields between source and target bean that share the same name ("wildcard mapping"). Listing fields in mapping definitions does not override this behaviour, except for the given fields. For example, given the following classes

class Person {
    private String firstName;
    private String lastName;
}

class Contact {
    private String firstName;
    private String surname;
}

and the mapping definition

<mapping>
    <class-a>com.github.dozermapper.core.vo.Person</class-a>
    <class-b>com.github.dozermapper.core.vo.Contact</class-b>
    <field>
        <a>lastName</a>
        <b>surname</b>
    </field>
</mapping>

a mapping from a Person object onto a Contact will map lastName to surname and firstName to firstName, even though the latter pair is not mentioned in the mapping definition.

You can disable wildcard mapping globally or at the class mapping level by setting wildcard to false. If you do, you have to explicitly specify each pair of fields that should be mapped:

<mapping wildcard="false">
    <class-a>com.github.dozermapper.core.vo.Person</class-a>
    <class-b>com.github.dozermapper.core.vo.Contact</class-b>
    <field>
        <a>lastName</a>
        <b>surname</b>
    </field>
    <field>
        <a>firstName</a>
        <b>firstName</b>
        </field>
</mapping>

Up to Dozer version 5.4.0, wildcard mappings were case insensitive. Current versions of Dozer only automatically map fields with the exact same name. You can enable the old case insensitive behaviour by setting the wildcard-case-insensitive policy to true. Then, for example a source field named camelCase will be mapped to target field camelcase (and vice versa).

Configuration via XML