| [[dozer-component]] |
| = Dozer Component |
| :page-source: components/camel-dozer/src/main/docs/dozer-component.adoc |
| |
| *Available as of Camel version 2.15* |
| |
| The Dozer component provides the ability to map between Java beans |
| using the http://camel.apache.org/dozer-type-conversion.html[Dozer] |
| mapping framework. Camel also supports the ability |
| to trigger Dozer mappings |
| http://camel.apache.org/dozer-type-conversion.html[as a type converter]. |
| The primary differences between using a Dozer endpoint and a Dozer |
| converter are: |
| |
| * The ability to manage Dozer mapping configuration on a per-endpoint |
| basis vs. global configuration via the converter registry. |
| * A Dozer endpoint can be configured to marshal/unmarshal input and |
| output data using Camel data formats to support a single, any-to-any |
| transformation endpoint |
| * The Dozer component allows for fine-grained integration and extension |
| of Dozer to support additional functionality (e.g. mapping literal |
| values, using expressions for mappings, etc.). |
| |
| In order to use the Dozer component, Maven users will need to add the |
| following dependency to their `pom.xml`: |
| |
| [source,xml] |
| ------------------------------------------------------------ |
| <dependency> |
| <groupId>org.apache.camel</groupId> |
| <artifactId>camel-dozer</artifactId> |
| <version>x.x.x</version> |
| <!-- use the same version as your Camel core version --> |
| </dependency> |
| ------------------------------------------------------------ |
| |
| == URI format |
| |
| The Dozer component only supports producer endpoints. |
| |
| [source,java] |
| -------------------------- |
| dozer:endpointId[?options] |
| -------------------------- |
| |
| Where *endpointId* is a name used to uniquely identify the Dozer |
| endpoint configuration. |
| |
| An example Dozer endpoint URI: |
| |
| [source,java] |
| --------------------------------------------------------------------------------------- |
| from("direct:orderInput"). |
| to("dozer:transformOrder?mappingFile=orderMapping.xml&targetModel=example.XYZOrder"). |
| to("direct:orderOutput"); |
| --------------------------------------------------------------------------------------- |
| |
| == Options |
| |
| // component options: START |
| The Dozer component supports 1 options, which are listed below. |
| |
| |
| |
| [width="100%",cols="2,5,^1,2",options="header"] |
| |=== |
| | Name | Description | Default | Type |
| | *basicPropertyBinding* (advanced) | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean |
| |=== |
| // component options: END |
| |
| // endpoint options: START |
| The Dozer endpoint is configured using URI syntax: |
| |
| ---- |
| dozer:name |
| ---- |
| |
| with the following path and query parameters: |
| |
| === Path Parameters (1 parameters): |
| |
| |
| [width="100%",cols="2,5,^1,2",options="header"] |
| |=== |
| | Name | Description | Default | Type |
| | *name* | *Required* A human readable name of the mapping. | | String |
| |=== |
| |
| |
| === Query Parameters (9 parameters): |
| |
| |
| [width="100%",cols="2,5,^1,2",options="header"] |
| |=== |
| | Name | Description | Default | Type |
| | *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean |
| | *mappingConfiguration* (producer) | The name of a DozerBeanMapperConfiguration bean in the Camel registry which should be used for configuring the Dozer mapping. This is an alternative to the mappingFile option that can be used for fine-grained control over how Dozer is configured. Remember to use a # prefix in the value to indicate that the bean is in the Camel registry (e.g. #myDozerConfig). | | DozerBeanMapperConfiguration |
| | *mappingFile* (producer) | The location of a Dozer configuration file. The file is loaded from the classpath by default, but you can use file:, classpath:, or http: to load the configuration from a specific location. | dozerBeanMapping.xml | String |
| | *marshalId* (producer) | The id of a dataFormat defined within the Camel Context to use for marshalling the mapping output to a non-Java type. | | String |
| | *sourceModel* (producer) | Fully-qualified class name for the source type used in the mapping. If specified, the input to the mapping is converted to the specified type before being mapped with Dozer. | | String |
| | *targetModel* (producer) | *Required* Fully-qualified class name for the target type used in the mapping. | | String |
| | *unmarshalId* (producer) | The id of a dataFormat defined within the Camel Context to use for unmarshalling the mapping input from a non-Java type. | | String |
| | *basicPropertyBinding* (advanced) | Whether the endpoint should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean |
| | *synchronous* (advanced) | Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported). | false | boolean |
| |=== |
| // endpoint options: END |
| // spring-boot-auto-configure options: START |
| == Spring Boot Auto-Configuration |
| |
| When using Spring Boot make sure to use the following Maven dependency to have support for auto configuration: |
| |
| [source,xml] |
| ---- |
| <dependency> |
| <groupId>org.apache.camel</groupId> |
| <artifactId>camel-dozer-starter</artifactId> |
| <version>x.x.x</version> |
| <!-- use the same version as your Camel core version --> |
| </dependency> |
| ---- |
| |
| |
| The component supports 2 options, which are listed below. |
| |
| |
| |
| [width="100%",cols="2,5,^1,2",options="header"] |
| |=== |
| | Name | Description | Default | Type |
| | *camel.component.dozer.basic-property-binding* | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | Boolean |
| | *camel.component.dozer.enabled* | Enable dozer component | true | Boolean |
| |=== |
| // spring-boot-auto-configure options: END |
| |
| |
| == Using Data Formats with Dozer |
| |
| Dozer does not support non-Java sources and targets for mappings, so it |
| cannot, for example, map an XML document to a Java object on its own. |
| Luckily, Camel has extensive support for marshalling between Java and a |
| wide variety of formats using |
| http://camel.apache.org/data-format.html[data formats]. The Dozer |
| component takes advantage of this support by allowing you to specify |
| that input and output data should be passed through a data format prior |
| to processing via Dozer. You can always do this on your own outside the |
| call to Dozer, but supporting it directly in the Dozer component allows |
| you to use a single endpoints to configure any-to-any transformation |
| within Camel. |
| |
| As an example, let's say you wanted to map between an XML data structure |
| and a JSON data structure using the Dozer component. If you had the |
| following data formats defined in a Camel Context: |
| |
| [source,xml] |
| ----------------------------------------------- |
| <dataFormats> |
| <json library="Jackson" id="myjson"/> |
| <jaxb contextPath="org.example" id="myjaxb"/> |
| </dataFormats> |
| ----------------------------------------------- |
| |
| You could then configure a Dozer endpoint to unmarshal the input XML |
| using a JAXB data format and marshal the mapping output using Jackson. |
| |
| [source,xml] |
| ---------------------------------------------------------------------------------------------------------- |
| <endpoint uri="dozer:xml2json?marshalId=myjson&unmarshalId=myjaxb&targetModel=org.example.Order"/> |
| ---------------------------------------------------------------------------------------------------------- |
| |
| == Configuring Dozer |
| |
| All Dozer endpoints require a Dozer mapping configuration file which |
| defines mappings between source and target objects. The component will |
| default to a location of META-INF/dozerBeanMapping.xml if the |
| mappingFile or mappingConfiguration options are not specified on an |
| endpoint. If you need to supply multiple mapping configuration files |
| for a single endpoint or specify additional configuration options (e.g. |
| event listeners, custom converters, etc.), then you can use an instance |
| of `org.apache.camel.converter.dozer.DozerBeanMapperConfiguration`. |
| |
| [source,xml] |
| ------------------------------------------------------------------------------------------ |
| <bean id="mapper" class="org.apache.camel.converter.dozer.DozerBeanMapperConfiguration"> |
| <property name="mappingFiles"> |
| <list> |
| <value>mapping1.xml</value> |
| <value>mapping2.xml</value> |
| </list> |
| </property> |
| </bean> |
| ------------------------------------------------------------------------------------------ |
| |
| == Mapping Extensions |
| |
| The Dozer component implements a number of extensions to the Dozer |
| mapping framework as custom converters. These converters implement |
| mapping functions that are not supported directly by Dozer itself. |
| |
| === Variable Mappings |
| |
| Variable mappings allow you to map the value of a variable definition |
| within a Dozer configuration into a target field instead of using the |
| value of a source field. This is equivalent to constant mapping in |
| other mapping frameworks, where can you assign a literal value to a |
| target field. To use a variable mapping, simply define a variable |
| within your mapping configuration and then map from the VariableMapper |
| class into your target field of choice: |
| |
| [source,xml] |
| -------------------------------------------------------------------------------------------------------- |
| <mappings xmlns="http://dozermapper.github.io/schema/bean-mapping" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://dozermapper.github.io/schema/bean-mapping http://dozermapper.github.io/schema/bean-mapping.xsd"> |
| <configuration> |
| <variables> |
| <variable name="CUST_ID">ACME-SALES</variable> |
| </variables> |
| </configuration> |
| <mapping> |
| <class-a>org.apache.camel.component.dozer.VariableMapper</class-a> |
| <class-b>org.example.Order</class-b> |
| <field custom-converter-id="_variableMapping" custom-converter-param="${CUST_ID}"> |
| <a>literal</a> |
| <b>custId</b> |
| </field> |
| </mapping> |
| </mappings> |
| -------------------------------------------------------------------------------------------------------- |
| |
| === Custom Mappings |
| |
| Custom mappings allow you to define your own logic for how a source |
| field is mapped to a target field. They are similar in function to |
| Dozer customer converters, with two notable differences: |
| |
| * You can have multiple converter methods in a single class with custom |
| mappings. |
| * There is no requirement to implement a Dozer-specific interface with |
| custom mappings. |
| |
| A custom mapping is declared by using the built-in '_customMapping' |
| converter in your mapping configuration. The parameter to this |
| converter has the following syntax: |
| |
| [source,shell] |
| -------------------------- |
| [class-name][,method-name] |
| -------------------------- |
| |
| Method name is optional - the Dozer component will search for a method |
| that matches the input and output types required for a mapping. An |
| example custom mapping and configuration are provided below. |
| |
| [source,java] |
| -------------------------------------------------- |
| public class CustomMapper { |
| // All customer ids must be wrapped in "[ ]" |
| public Object mapCustomer(String customerId) { |
| return "[" + customerId + "]"; |
| } |
| } |
| -------------------------------------------------- |
| |
| [source,xml] |
| -------------------------------------------------------------------------------------------------------- |
| <mappings xmlns="http://dozermapper.github.io/schema/bean-mapping" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://dozermapper.github.io/schema/bean-mapping http://dozermapper.github.io/schema/bean-mapping.xsd"> |
| <mapping> |
| <class-a>org.example.A</class-a> |
| <class-b>org.example.B</class-b> |
| <field custom-converter-id="_customMapping" |
| custom-converter-param="org.example.CustomMapper,mapCustomer"> |
| <a>header.customerNum</a> |
| <b>custId</b> |
| </field> |
| </mapping> |
| </mappings> |
| -------------------------------------------------------------------------------------------------------- |
| |
| === Expression Mappings |
| |
| Expression mappings allow you to use the powerful |
| http://camel.apache.org/languages.html[language] capabilities of Camel |
| to evaluate an expression and assign the result to a target field in a |
| mapping. Any language that Camel supports can be used in an expression |
| mapping. Basic examples of expressions include the ability to map a |
| Camel message header or exchange property to a target field or to |
| concatenate multiple source fields into a target field. The syntax of a |
| mapping expression is: |
| |
| [source,shell] |
| ----------------------- |
| [language]:[expression] |
| ----------------------- |
| |
| An example of mapping a message header into a target field: |
| |
| [source,xml] |
| -------------------------------------------------------------------------------------------------------------- |
| <mappings xmlns="http://dozermapper.github.io/schema/bean-mapping" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://dozermapper.github.io/schema/bean-mapping http://dozermapper.github.io/schema/bean-mapping.xsd"> |
| <mapping> |
| <class-a>org.apache.camel.component.dozer.ExpressionMapper</class-a> |
| <class-b>org.example.B</class-b> |
| <field custom-converter-id="_expressionMapping" custom-converter-param="simple:\${header.customerNumber}"> |
| <a>expression</a> |
| <b>custId</b> |
| </field> |
| </mapping> |
| </mappings> |
| -------------------------------------------------------------------------------------------------------------- |
| |
| Note that any properties within your expression must be escaped with "\" |
| to prevent an error when Dozer attempts to resolve variable values |
| defined using the EL. |