[8/8] camel git commit: Added JSON Xstream Dataformat docs to Gitbook

[ac...@apache.org]

Added JSON Xstream Dataformat 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/8d186c02
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/8d186c02
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/8d186c02

Branch: refs/heads/master
Commit: 8d186c028a4d40c4fe9dcfc06a48e2b3d1351140
Parents: 95835a8
Author: Andrea Cosentino <an...@gmail.com>
Authored: Wed Aug 31 10:20:43 2016 +0200
Committer: Andrea Cosentino <an...@gmail.com>
Committed: Wed Aug 31 10:20:43 2016 +0200

----------------------------------------------------------------------
 .../src/main/docs/json-xstream-dataformat.adoc  | 157 +++++++++++++++++++
 1 file changed, 157 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/camel/blob/8d186c02/components/camel-xstream/src/main/docs/json-xstream-dataformat.adoc
----------------------------------------------------------------------
diff --git a/components/camel-xstream/src/main/docs/json-xstream-dataformat.adoc b/components/camel-xstream/src/main/docs/json-xstream-dataformat.adoc
new file mode 100644
index 0000000..f310620
--- /dev/null
+++ b/components/camel-xstream/src/main/docs/json-xstream-dataformat.adoc
@@ -0,0 +1,157 @@
+[[XStream-XStream]]
+XStream
+~~~~~~~
+
+XStream is a link:data-format.html[Data Format] which uses the
+http://xstream.codehaus.org/[XStream library] to marshal and unmarshal
+Java objects to and from XML.
+
+To use XStream in your camel routes you need to add the a dependency
+on�*camel-xstream*�which implements this data format.
+
+Maven users will need to add the following dependency to their
+`pom.xml`�for this component:
+
+[source,xml]
+----------------------------------------------------------
+<dependency>
+  <groupId>org.apache.camel</groupId>
+  <artifactId>camel-xstream</artifactId>
+  <version>x.x.x</version>
+  <!-- use the same version as your Camel core version -->
+</dependency>
+----------------------------------------------------------
+
+[[XStream-Options]]
+Options
+^^^^^^^
+
+// dataformat options: START
+The JSon XStream dataformat supports 15 options which are listed below.
+
+
+
+{% raw %}
+[width="100%",cols="2s,1m,1m,6",options="header"]
+|=======================================================================
+| Name | Default | Java Type | Description
+| objectMapper |  | String | Lookup and use the existing ObjectMapper with the given id when using Jackson.
+| prettyPrint | false | Boolean | To enable pretty printing output nicely formatted. Is by default false.
+| library | XStream | JsonLibrary | Which json library to use.
+| unmarshalTypeName |  | String | Class name of the java type to use when unarmshalling
+| jsonView |  | Class<?> | When marshalling a POJO to JSON you might want to exclude certain fields from the JSON output. With Jackson you can use JSON views to accomplish this. This option is to refer to the class which has JsonView annotations
+| include |  | String | If you want to marshal a pojo to JSON and the pojo has some fields with null values. And you want to skip these null values you can set this option to NOT_NULL
+| allowJmsType | false | Boolean | Used for JMS users to allow the JMSType header from the JMS spec to specify a FQN classname to use to unmarshal to.
+| collectionTypeName |  | String | Refers to a custom collection type to lookup in the registry to use. This option should rarely be used but allows to use different collection types than java.util.Collection based as default.
+| useList | false | Boolean | To unarmshal to a List of Map or a List of Pojo.
+| enableJaxbAnnotationModule | false | Boolean | Whether to enable the JAXB annotations module when using jackson. When enabled then JAXB annotations can be used by Jackson.
+| moduleClassNames |  | String | To use custom Jackson modules com.fasterxml.jackson.databind.Module specified as a String with FQN class names. Multiple classes can be separated by comma.
+| moduleRefs |  | String | To use custom Jackson modules referred from the Camel registry. Multiple modules can be separated by comma.
+| enableFeatures |  | String | Set of features to enable on the Jackson com.fasterxml.jackson.databind.ObjectMapper. The features should be a name that matches a enum from com.fasterxml.jackson.databind.SerializationFeature com.fasterxml.jackson.databind.DeserializationFeature or com.fasterxml.jackson.databind.MapperFeature Multiple features can be separated by comma
+| disableFeatures |  | String | Set of features to disable on the Jackson com.fasterxml.jackson.databind.ObjectMapper. The features should be a name that matches a enum from com.fasterxml.jackson.databind.SerializationFeature com.fasterxml.jackson.databind.DeserializationFeature or com.fasterxml.jackson.databind.MapperFeature Multiple features can be separated by comma
+| permissions |  | String | Adds permissions that controls which Java packages and classes XStream is allowed to use during unmarshal from xml/json to Java beans. A permission must be configured either here or globally using a JVM system property. The permission can be specified in a syntax where a plus sign is allow and minus sign is deny. Wildcards is supported by using . as prefix. For example to allow com.foo and all subpackages then specfy com.foo.. Multiple permissions can be configured separated by comma such as com.foo.-com.foo.bar.MySecretBean. The following default permission is always included: -java.lang.java.util. unless its overridden by specifying a JVM system property with they key org.apache.camel.xstream.permissions.
+|=======================================================================
+{% endraw %}
+// dataformat options: END
+
+
+[[XStream-UsingtheJavaDSL]]
+Using the Java DSL
+^^^^^^^^^^^^^^^^^^
+
+[source,java]
+-----------------------------------------------------------
+// lets turn Object messages into XML then send to MQSeries
+from("activemq:My.Queue").
+  marshal().xstream().
+  to("mqseries:Another.Queue");
+-----------------------------------------------------------
+
+If you would like to configure the `XStream` instance used by the Camel
+for the message transformation, you can simply pass a reference to that
+instance on the DSL level.
+
+[source,java]
+---------------------------------------------------------
+XStream xStream = new XStream();
+xStream.aliasField("money", PurchaseOrder.class, "cash");
+// new Added setModel option since Camel 2.14
+xStream.setModel("NO_REFERENCES");
+...
+
+from("direct:marshal").
+  marshal(new XStreamDataFormat(xStream)).
+  to("mock:marshaled");
+---------------------------------------------------------
+
+[[XStream-XMLInputFactoryandXMLOutputFactory]]
+XMLInputFactory and XMLOutputFactory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+http://xstream.codehaus.org/[The XStream library] uses the
+`javax.xml.stream.XMLInputFactory` and
+`javax.xml.stream.XMLOutputFactory`, you can control which
+implementation of this factory should be used.
+
+The Factory is discovered using this algorithm: 
+ 1. Use the `javax.xml.stream.XMLInputFactory` ,
+`javax.xml.stream.XMLOutputFactory` system property. 
+ 2. Use the `lib/xml.stream.properties` file in the `JRE_HOME`
+directory. 
+ 3. Use the Services API, if available, to determine the classname by
+looking in the `META-INF/services/javax.xml.stream.XMLInputFactory`,
+`META-INF/services/javax.xml.stream.XMLOutputFactory` files in jars
+available to the JRE. 
+ 4. Use the platform default XMLInputFactory,XMLOutputFactory instance.
+
+[[XStream-HowtosettheXMLencodinginXstreamDataFormat]]
+How to set the XML encoding in Xstream DataFormat?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+From Camel 2.2.0, you can set the encoding of XML in Xstream DataFormat
+by setting the Exchange's property with the key `Exchange.CHARSET_NAME`,
+or setting the encoding property on Xstream from DSL or Spring config.
+
+[source,java]
+-------------------------------
+from("activemq:My.Queue").
+  marshal().xstream("UTF-8").
+  to("mqseries:Another.Queue");
+-------------------------------
+
+[[XStream-SettingthetypepermissionsofXstreamDataFormat]]
+Setting the type permissions of Xstream DataFormat
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In Camel, one can always use its own processing step in the route to
+filter and block certain XML documents to be routed to the XStream's
+unmarhall step. From Camel 2.16.1, 2.15.5, you can
+set�http://x-stream.github.io/security.html[XStream's type
+permissions]�to automatically allow or deny the instantiation of certain
+types.
+
+The default type permissions setting used by Camel denies all types
+except for those from java.lang and java.util packages. This setting can
+be changed by setting System property
+org.apache.camel.xstream.permissions. Its value is a string of
+comma-separated permission terms, each representing a type being allowed
+or denied, depending on whether the term is prefixed with '+' (note '+'
+may be omitted) or with '-', respectively.
+
+Each term may contain a wildcard character '*'. For example, value
+"-*,java.lang.*,java.util.*" indicates denying all types except for
+java.lang.* and java.util.* classes. Setting this value to an empty
+string "" reverts to the default XStream's type permissions handling
+which denies certain blacklisted classes and allow others.
+
+The type permissions setting can be extended at an individual XStream
+DataFormat instance by setting its type permissions property.
+
+[source,java]
+-------------------------------------------------------------------
+    <dataFormats>
+        <xstream id="xstream-default" 
+                 permissions="org.apache.camel.samples.xstream.*"/>
+        ...
+
+-------------------------------------------------------------------