Repository: camel Updated Branches: refs/heads/master 7c97811a5 -> 7fea5338e
Added camel-jacksonxml 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/7fea5338 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/7fea5338 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/7fea5338 Branch: refs/heads/master Commit: 7fea5338e969e2ec8ae6eb6493156c58456ac5b9 Parents: 7c97811 Author: Andrea Cosentino <[email protected]> Authored: Fri Jun 24 09:05:02 2016 +0200 Committer: Andrea Cosentino <[email protected]> Committed: Fri Jun 24 09:05:02 2016 +0200 ---------------------------------------------------------------------- .../src/main/docs/jackson-xml.adoc | 352 +++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 2 files changed, 353 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/7fea5338/components/camel-jacksonxml/src/main/docs/jackson-xml.adoc ---------------------------------------------------------------------- diff --git a/components/camel-jacksonxml/src/main/docs/jackson-xml.adoc b/components/camel-jacksonxml/src/main/docs/jackson-xml.adoc new file mode 100644 index 0000000..e2d05be --- /dev/null +++ b/components/camel-jacksonxml/src/main/docs/jackson-xml.adoc @@ -0,0 +1,352 @@ +[[JacksonXML-JacksonXML]] +Jackson XML +~~~~~~~~~~~ + +*Available as of Camel 2.16* + +Jackson XML is a link:data-format.html[Data Format] which uses the +http://wiki.fasterxml.com/JacksonHome/[Jackson library] with the +https://github.com/FasterXML/jackson-dataformat-xml[XMLMapper extension] +to unmarshal an XML payload into Java objects or to marshal Java objects +into an XML payload. + +INFO:If you are familiar with Jackson, this XML data format behaves in the +same way as its JSON counterpart, and thus can be used with classes +annotated for JSON serialization/deserialization. + +This extension also mimics +https://github.com/FasterXML/jackson-dataformat-xml/blob/master/README.md[JAXB's +"Code first" approach]. + +This data format relies on +http://wiki.fasterxml.com/WoodstoxHome[Woodstox] (especially for +features like pretty printing), a fast and efficient XML processor. + +[source,java] +------------------------------- +from("activemq:My.Queue"). + unmarshal().jacksonxml(). + to("mqseries:Another.Queue"); +------------------------------- + +[[JacksonXML-UsingJacksonXMLinSpringDSL]] +Using Jackson XML in Spring DSL ++++++++++++++++++++++++++++++++ + +When using link:data-format.html[Data Format] in Spring DSL you need to +declare the data formats first. This is done in the *DataFormats* XML +tag. + +[source,xml] +----------------------------------------------------------------------------------------------------------------------------- + <dataFormats> + <!-- here we define a Xml data format with the id jack and that it should use the TestPojo as the class type when + doing unmarshal. The unmarshalTypeName is optional, if not provided Camel will use a Map as the type --> + <jacksonxml id="jack" unmarshalTypeName="org.apache.camel.component.jacksonxml.TestPojo"/> + </dataFormats> +----------------------------------------------------------------------------------------------------------------------------- + +And then you can refer to this id in the route: + +[source,xml] +------------------------------------- + <route> + <from uri="direct:back"/> + <unmarshal ref="jack"/> + <to uri="mock:reverse"/> + </route> +------------------------------------- + +[[JacksonXML-ExcludingPOJOfieldsfrommarshalling]] +Excluding POJO fields from marshalling +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When marshalling a POJO to XML you might want to exclude certain fields +from the XML output. With Jackson you can +use http://wiki.fasterxml.com/JacksonJsonViews[JSON views] to accomplish +this. First create one or more marker classes. + +Use the marker classes with the `@JsonView` annotation to +include/exclude certain fields. The annotation also works on getters. + +Finally use the Camel `JacksonXMLDataFormat` to marshall the above POJO +to XML. + +Note that the weight field is missing in the resulting XML: + +[source,java] +---------------------------- +<pojo age="30" weight="70"/> +---------------------------- + +[[JacksonXML-Include/ExcludefieldsusingthejsonViewattributewithJacksonXMLDataFormat]] +Include/Exclude fields using the `jsonView` attribute with `JacksonXML`DataFormat +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As an example of using this attribute you can instead of: + +[source,java] +--------------------------------------------------------------------------------------------------- +JacksonXMLDataFormat ageViewFormat = new JacksonXMLDataFormat(TestPojoView.class, Views.Age.class); +from("direct:inPojoAgeView"). + marshal(ageViewFormat); +--------------------------------------------------------------------------------------------------- + +Directly specify your http://wiki.fasterxml.com/JacksonJsonViews[JSON +view] inside the Java DSL as: + +[source,java] +------------------------------------------------------------ +from("direct:inPojoAgeView"). + marshal().jacksonxml(TestPojoView.class, Views.Age.class); +------------------------------------------------------------ + +And the same in XML DSL: + +[source,xml] +--------------------------------------------------------------------------------------------------------------------------------------------------- +<from uri="direct:inPojoAgeView"/> + <marshal> + <jacksonxml unmarshalTypeName="org.apache.camel.component.jacksonxml.TestPojoView" jsonView="org.apache.camel.component.jacksonxml.Views$Age"/> + </marshal> +--------------------------------------------------------------------------------------------------------------------------------------------------- + +[[JacksonXML-Settingserializationincludeoption]] +Setting serialization include option +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you want to marshal a pojo to XML, and the pojo has some fields with +null values. And you want to skip these null values, then you need to +set either an annotation on the pojo, + +[source,java] +------------------------------ +@JsonInclude(Include.NON_NULL) +public class MyPojo { + ... +} +------------------------------ + +But this requires you to include that annotation in your pojo source +code. You can also configure the Camel JacksonXMLDataFormat to set the +include option, as shown below: + +[source,java] +--------------------------------------------------------- +JacksonXMLDataFormat format = new JacksonXMLDataFormat(); +format.setInclude("NON_NULL"); +--------------------------------------------------------- + +Or from XML DSL you configure this as + +[source,java] +------------------------------------------------------ + <dataFormats> + <jacksonxml id="jacksonxml" include="NOT_NULL"/> + </dataFormats> +------------------------------------------------------ + +[[JacksonXML-UnmarshallingfromXMLtoPOJOwithdynamicclassname]] +Unmarshalling from XML to POJO with dynamic class name +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you use jackson to unmarshal XML to POJO, then you can now specify a +header in the message that indicate which class name to unmarshal to. + +The header has key `CamelJacksonUnmarshalType` if that header is present +in the message, then Jackson will use that as FQN for the POJO class to +unmarshal the XML payload as. + + For JMS end users there is the JMSType header from the JMS spec that +indicates that also. To enable support for JMSType you would need to +turn that on, on the jackson data format as shown: + +[source,java] +--------------------------------------------------- +JacksonDataFormat format = new JacksonDataFormat(); +format.setAllowJmsType(true); +--------------------------------------------------- + +Or from XML DSL you configure this as + +[source,java] +------------------------------------------------------- + <dataFormats> + <jacksonxml id="jacksonxml" allowJmsType="true"/> + </dataFormats> +------------------------------------------------------- + +[[JacksonXML-UnmarshallingfromXMLtoListMaporListPojo]] +Unmarshalling from XML to List<Map> or List<pojo> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you are using Jackson to unmarshal XML to a list of map/pojo, you can +now specify this by setting `useList="true"` or use +the `org.apache.camel.component.jacksonxml.ListJacksonXMLDataFormat`. +For example with Java you can do as shown below: + +[source,java] +------------------------------------------------------------- +JacksonXMLDataFormat format = new ListJacksonXMLDataFormat(); +// or +JacksonXMLDataFormat format = new JacksonXMLDataFormat(); +format.useList(); +// and you can specify the pojo class type also +format.setUnmarshalType(MyPojo.class); +------------------------------------------------------------- + +And if you use XML DSL then you configure to use list +using `useList` attribute as shown below: + +[source,java] +-------------------------------------------- + <dataFormats> + <jacksonxml id="jack" useList="true"/> + </dataFormats> +-------------------------------------------- + +And you can specify the pojo type also + +[source,java] +------------------------------------------------------------------------------- + <dataFormats> + <jacksonxml id="jack" useList="true" unmarshalTypeName="com.foo.MyPojo"/> + </dataFormats> +------------------------------------------------------------------------------- + +[[JacksonXML-UsingcustomJacksonmodules]] +Using custom Jackson modules +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can use custom Jackson modules by specifying the class names of +those using the moduleClassNames option as shown below. + +[source,java] +----------------------------------------------------------------------------------------------------------------------------------------- + <dataFormats> + <jacksonxml id="jack" useList="true" unmarshalTypeName="com.foo.MyPojo" moduleClassNames="com.foo.MyModule,com.foo.MyOtherModule"/> + </dataFormats> +----------------------------------------------------------------------------------------------------------------------------------------- + +When using moduleClassNames then the custom jackson modules are not +configured, by created using default constructor and used as-is. If a +custom module needs any custom configuration, then an instance of the +module can be created and configured, and then use modulesRefs to refer +to the module as shown below: + +[source,java] +------------------------------------------------------------------------------------------------------------------ + <bean id="myJacksonModule" class="com.foo.MyModule"> + ... // configure the module as you want + </bean> + + <dataFormats> + <jacksonxml id="jacksonxml" useList="true" unmarshalTypeName="com.foo.MyPojo" moduleRefs="myJacksonModule"/> + </dataFormats> +------------------------------------------------------------------------------------------------------------------ + + Multiple modules can be specified separated by comma, such as +moduleRefs="myJacksonModule,myOtherModule" + +[[JacksonXML-EnablingordisablefeaturesusingJackson]] +Enabling or disable features using Jackson +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Jackson has a number of features you can enable or disable, which its +ObjectMapper uses. For example to disable failing on unknown properties +when marshalling, you can configure this using the disableFeatures: + +[source,java] +------------------------------------------------------------------------------------------------------------------- + <dataFormats> + <jacksonxml id="jacksonxml" unmarshalTypeName="com.foo.MyPojo" disableFeatures="FAIL_ON_UNKNOWN_PROPERTIES"/> + </dataFormats> +------------------------------------------------------------------------------------------------------------------- + +You can disable multiple features by separating the values using comma. +The values for the features must be the name of the enums from Jackson +from the following enum classes + +* com.fasterxml.jackson.databind.SerializationFeature +* com.fasterxml.jackson.databind.DeserializationFeature +* com.fasterxml.jackson.databind.MapperFeature + +To enable a feature use the enableFeatures options instead. + +From Java code you can use the type safe methods from camel-jackson +module: + +[source,java] +---------------------------------------------------------------------- +JacksonDataFormat df = new JacksonDataFormat(MyPojo.class); +df.disableFeature(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES); +df.disableFeature(DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES); +---------------------------------------------------------------------- + +[[JacksonXML-ConvertingMapstoPOJOusingJackson]] +Converting Maps to POJO using Jackson +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Jackson `ObjectMapper` can be used to convert maps to POJO objects. +Jackson component comes with the data converter that can be used to +convert `java.util.Map` instance to non-String, non-primitive and +non-Number objects. + +[source,java] +---------------------------------------------------------------- +Map<String, Object> invoiceData = new HashMap<String, Object>(); +invoiceData.put("netValue", 500); +producerTemplate.sendBody("direct:mapToInvoice", invoiceData); +... +// Later in the processor +Invoice invoice = exchange.getIn().getBody(Invoice.class); +---------------------------------------------------------------- + +If there is a single `ObjectMapper` instance available in the Camel +registry, it will used by the converter to perform the conversion. +Otherwise the default mapper will be used.  + +[[JacksonXML-FormattedXMLmarshallingpretty-printing]] +Formatted XML marshalling (pretty-printing) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Using the `prettyPrint` option one can output a well formatted XML while +marshalling: + +[source,java] +------------------------------------------------ + <dataFormats> + <jacksonxml id="jack" prettyPrint="true"/> + </dataFormats> +------------------------------------------------ + +And in Java DSL: + +[source,java] +--------------------------------------------------- +from("direct:inPretty").marshal().jacksonxml(true); +--------------------------------------------------- + +Please note that there are 5 different overloaded `jacksonxml()` DSL +methods which support the `prettyPrint` option in combination with other +settings for `unmarshalType`, `jsonView` etc. + +[[JacksonXML-Dependencies]] +Dependencies +^^^^^^^^^^^^ + +To use Jackson XML in your camel routes you need to add the dependency +on *camel-jacksonxml* which implements this data format. + +If you use maven you could just add the following to your pom.xml, +substituting the version number for the latest & greatest release (see +link:download.html[the download page for the latest versions]). + +[source,xml] +---------------------------------------------------------- +<dependency> + <groupId>org.apache.camel</groupId> + <artifactId>camel-jacksonxml</artifactId> + <version>x.x.x</version> + <!-- use the same version as your Camel core version --> +</dependency> +---------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/7fea5338/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index b06da0b..509d650 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -318,6 +318,7 @@ * [BeanIO](beanio.adoc) * [Flatpack](flatpack-dataformat.adoc) * [Ical](ical.adoc) + * [Jackson XML](jackson-xml.adoc) * [Jaxb](jaxb.adoc) * [Jibx](jibx.adoc) * [Lzf](lzf.adoc)
