You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ac...@apache.org on 2016/06/24 07:15:53 UTC
camel git commit: Added camel-jacksonxml docs to Gitbook
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 <an...@gmail.com>
Authored: Fri Jun 24 09:05:02 2016 +0200
Committer: Andrea Cosentino <an...@gmail.com>
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)