Repository: camel Updated Branches: refs/heads/master 3af343934 -> 83e97655c
CAMEL-10447 Added Transformer adoc Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/83e97655 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/83e97655 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/83e97655 Branch: refs/heads/master Commit: 83e97655cc34ef848e8cc352af157396dec807da Parents: 3af3439 Author: Tomohisa Igarashi <tm.igara...@gmail.com> Authored: Fri Nov 25 19:22:43 2016 +0900 Committer: Claus Ibsen <davscl...@apache.org> Committed: Fri Nov 25 11:26:08 2016 +0100 ---------------------------------------------------------------------- camel-core/src/main/docs/transformer.adoc | 176 +++++++++++++++++++++++++ 1 file changed, 176 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/83e97655/camel-core/src/main/docs/transformer.adoc ---------------------------------------------------------------------- diff --git a/camel-core/src/main/docs/transformer.adoc b/camel-core/src/main/docs/transformer.adoc new file mode 100644 index 0000000..d8020db --- /dev/null +++ b/camel-core/src/main/docs/transformer.adoc @@ -0,0 +1,176 @@ +[[Transformer-Transformer]] +Transformer +^^^^^^^^^^^^ + +*Available as of Camel 2.19* + +Transformer performs declarative transformation of the message according +to the declared link:eips/inputType-eip.html[Input Type] and/or +link:eips/outputType-eip.html[Output Type] on a route definition which declares the expected +message type. +There are two Exchange property indicates current message type, `Exchange.INPUT_TYPE` +holds input message type and `Exchange.OUTPUT_TYPE` holds output message type. If the +input type and/or output type declared by link:eips/inputType-eip.html[Input Type] and/or +link:eips/outputType-eip.html[Output Type] in the route definition, and it is different from +those properties at runtime, camel internal processor look for a Transformer which transforms +from the current message type to the expected message type and apply. Once transform succeed or message +is already in expected type, then `Exchange.INPUT_TYPE` or `Exchange.OUTPUT_TYPE` is updated. + + + +[[Transformer-DataTypeFormat]] +Data type format +^^^^^^^^^^^^^^^ +[source,java] +--------------------------------------------- +scheme:name +--------------------------------------------- +where *scheme* is the type of data model like `java`, `xml` or `json`, and *name* is the individual +data type name. If you only specify *scheme* then it hits all the data types which has that scheme like +a wildcard. + + + +[[Transformer-SupportedTransformers]] +Supported Transformers +^^^^^^^^^^^^^^^^^^^^^ + +|======================================================================= +| Transformer | Description + +| Data Format Transformer | Transform with using link:data-format.html[Data Format] + +| Endpoint Transformer | Transform with using link:endpoint.html[Endpoint] + +| Custom Transformer | Transform with using custom transformer class. Transformer must be a subclass of `org.apache.camel.spi.Transformer` +|======================================================================= + + + +[[Transformer-CommonOptions]] +Common Options +^^^^^^^^^^^^^ +All transformers have following common options to specify which data type is supported by the transformer. `scheme` or both of `from` and `to` must be specified. +|======================================================================= +| Name | Description + +| scheme | Type of data model like `xml` or `json`. For example if `xml` is specified, the transformer is applied for all java -> xml and xml -> java transformation. + +| from | <<Transformer-DataTypeFormat,Data type>> to transform from. + +| to | <<Transformer-DataTypeFormat,Data type>> to transform to. +|======================================================================= + + + +[[Transformer-DataFormat]] +DataFormat Transformer Options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +|======================================================================= +| Name | Description + +| type | link:data-format.html[Data Format] type + +| ref | reference to the link:data-format.html[Data Format] ID +|======================================================================= +Here is an example to specify bindy DataFormat type in XML DSL: +[source,xml] +------------------------------------------------------------------- +<dataFormatTransformer from="java:com.example.Order" to="csv:CSVOrder"> + <bindy id="csvdf" type="Csv" classType="com.example.Order"/> +</dataFormatTransformer> +------------------------------------------------------------------- + + + +[[Transformer-Endpoint]] +Endpoint Transformer Options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +|======================================================================= +| Name | Description + +| ref | Reference to the link:endpoint.html[Endpoint] ID + +| uri | link:endpoint.html[Endpoint] URI +|======================================================================= +Here is an example to specify endpoint ref in XML DSL: +[source,xml] +------------------------------------------------------------------- +<endpointTransformer ref="myDozerEndpoint" from="xml" to="json"/> +------------------------------------------------------------------- + + + +[[Transformer-Custom]] +Custom Transformer Options +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Note that Transformer must be a subclass of `org.apache.camel.spi.Transformer` +|======================================================================= +| Name | Description + +| ref | Reference to the custom Transformer bean ID + +| type | Fully qualified class name of the custom Transformer class +|======================================================================= +Here is an example to specify custom Transformer class in XML DSL: +[source,xml] +------------------------------------------------------------------- +<customTransformer type="com.example.MyCustomTransformer" from="xml" to="json"/> +------------------------------------------------------------------- + + + +[[Transformer-Examples]] +Examples +^^^^^^^ + +For example to declare the Endpoint Transformer which uses +xslt component to transform from `xml:ABCOrder` to `xml:XYZOrder`, we can do as follows: + +Java DSL: +[source,java] +------------------------------------------------------------------- +// TODO implement fluent builder for transformers +------------------------------------------------------------------- + +XML DSL: +[source,xml] +------------------------------------------------------------------- +<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring";> + <transformers> + <endpointTransformer uri="xslt:transform.xsl" from="xml:ABCOrder" to="xml:XYZOrder"/> + </transformers> + .... +</camelContext> +------------------------------------------------------------------- + +If you have following route definition, above transformer will be applied when `direct:abc` endpoint sends the message to `direct:xyz`: + +Java DSL: +[source,java] +------------------------------------------------------------------- +from("direct:abc") + .inputType("xml:ABCOrder") + .to("direct:xyz"); +from("direct:xyz") + .inputType("xml:XYZOrder") + .to("somewhere:else"); +------------------------------------------------------------------- + +XML DSL: +[source,xml] +------------------------------------------------------------------- +<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring";> + .... + <route> + <from uri="direct:abc"/> + <inputType urn="xml:ABCOrder"/> + <to uri="direct:xyz"/> + </route> + <route> + <from uri="direct:xyz"/> + <inputType urn="xml:XYZOrder"/> + <to uri="somewhere:else"/> + </route> +</camelContext> +-------------------------------------------------------------------
