camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From acosent...@apache.org
Subject camel git commit: Added camel-dozer docs to gitbook
Date Tue, 01 Mar 2016 15:49:37 GMT
Repository: camel
Updated Branches:
  refs/heads/master 3c1c32d92 -> 2fefcc99b


Added camel-dozer docs to gitbook


Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/2fefcc99
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/2fefcc99
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/2fefcc99

Branch: refs/heads/master
Commit: 2fefcc99bc2a2faaa912bf691f0fb60d3f249f24
Parents: 3c1c32d
Author: Andrea Cosentino <ancosen@gmail.com>
Authored: Tue Mar 1 16:48:54 2016 +0100
Committer: Andrea Cosentino <ancosen@gmail.com>
Committed: Tue Mar 1 16:48:54 2016 +0100

----------------------------------------------------------------------
 components/camel-dozer/src/main/docs/dozer.adoc | 286 +++++++++++++++++++
 docs/user-manual/en/SUMMARY.md                  |   1 +
 2 files changed, 287 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/camel/blob/2fefcc99/components/camel-dozer/src/main/docs/dozer.adoc
----------------------------------------------------------------------
diff --git a/components/camel-dozer/src/main/docs/dozer.adoc b/components/camel-dozer/src/main/docs/dozer.adoc
new file mode 100644
index 0000000..d75be57
--- /dev/null
+++ b/components/camel-dozer/src/main/docs/dozer.adoc
@@ -0,0 +1,286 @@
+[[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.
+

http://git-wip-us.apache.org/repos/asf/camel/blob/2fefcc99/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index b2b9926..a0174b3 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -119,6 +119,7 @@
 	* [Disruptor](disruptor.adoc)
 	* [DNS](dns.adoc)
 	* [Docker](docker.adoc)
+	* [Dozer](dozer.adoc)
 	* [Ironmq](ironmq.adoc)
 	* [JMS](jms.adoc)
 	* [Metrics](metrics.adoc)


Mime
View raw message