components/camel-dozer/src/main/docs/dozer.adoc - camel - Git at Google

 [[Dozer-Dozer]]
 Dozer
 ~~~~~

 The *dozer:* component provides the ability to map between Java beans
 using the http://camel.apache.org/dozer-type-conversion.html[Dozer]
 mapping framework since *Camel 2.15.0*.  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>
 ------------------------------------------------------------

 [[Dozer-URIformat]]
 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");
 ---------------------------------------------------------------------------------------

 [[Dozer-Options]]
 Options
 ^^^^^^^

 [width="100%",cols="10%,10%,80%",options="header",]
 |=======================================================================
 |Name |Default |Description

 |`mappingFile` |dozerBeanMapping.xml |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.

 |`unmarshalId` |none |The id of a dataFormat defined within the Camel Context to use for
 unmarshalling the mapping input from a non-Java type.

 |`marshalId` |none |The id of a dataFormat defined within the Camel Context to use for
 marshalling the mapping output to a non-Java type.

 |`sourceModel` |none |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.

 |`targetModel` |none |Fully-qualified class name for the target type used in the mapping. This
 option is required.

 |`mappingConfiguration` |none |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").
 |=======================================================================

 [[Dozer-UsingDataFormatswithDozer]]
 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&amp;unmarshalId=myjaxb&amp;targetModel=org.example.Order"/>
 ----------------------------------------------------------------------------------------------------------

 [[Dozer-ConfiguringDozer]]
 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>
 ------------------------------------------------------------------------------------------

 [[Dozer-MappingExtensions]]
 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.

 [[Dozer-VariableMappings]]
 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://dozer.sourceforge.net"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://dozer.sourceforge.net http://dozer.sourceforge.net/schema/beanmapping.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>
 --------------------------------------------------------------------------------------------------------

 [[Dozer-CustomMappings]]
 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://dozer.sourceforge.net"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://dozer.sourceforge.net http://dozer.sourceforge.net/schema/beanmapping.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>
 --------------------------------------------------------------------------------------------------------

 [[Dozer-ExpressionMappings]]
 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://dozer.sourceforge.net"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://dozer.sourceforge.net http://dozer.sourceforge.net/schema/beanmapping.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.
	[[Dozer-Dozer]]
	Dozer
	~~~~~

	The dozer: component provides the ability to map between Java beans
	using the http://camel.apache.org/dozer-type-conversion.html[Dozer]
	mapping framework since Camel 2.15.0. 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>
	------------------------------------------------------------

	[[Dozer-URIformat]]
	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");
	---------------------------------------------------------------------------------------

	[[Dozer-Options]]
	Options
	^^^^^^^

	[width="100%",cols="10%,10%,80%",options="header",]
	\|=======================================================================
	\|Name \|Default \|Description

	\|`mappingFile` \|dozerBeanMapping.xml \|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.

	\|`unmarshalId` \|none \|The id of a dataFormat defined within the Camel Context to use for
	unmarshalling the mapping input from a non-Java type.

	\|`marshalId` \|none \|The id of a dataFormat defined within the Camel Context to use for
	marshalling the mapping output to a non-Java type.

	\|`sourceModel` \|none \|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.

	\|`targetModel` \|none \|Fully-qualified class name for the target type used in the mapping. This
	option is required.

	\|`mappingConfiguration` \|none \|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").
	\|=======================================================================

	[[Dozer-UsingDataFormatswithDozer]]
	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"/>
	----------------------------------------------------------------------------------------------------------

	[[Dozer-ConfiguringDozer]]
	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>
	------------------------------------------------------------------------------------------

	[[Dozer-MappingExtensions]]
	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.

	[[Dozer-VariableMappings]]
	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://dozer.sourceforge.net"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://dozer.sourceforge.net http://dozer.sourceforge.net/schema/beanmapping.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>
	--------------------------------------------------------------------------------------------------------

	[[Dozer-CustomMappings]]
	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://dozer.sourceforge.net"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://dozer.sourceforge.net http://dozer.sourceforge.net/schema/beanmapping.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>
	--------------------------------------------------------------------------------------------------------

	[[Dozer-ExpressionMappings]]
	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://dozer.sourceforge.net"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://dozer.sourceforge.net http://dozer.sourceforge.net/schema/beanmapping.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.