camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From acosent...@apache.org
Subject [2/8] camel git commit: Added camel-xstream docs to Gitbook
Date Thu, 09 Jun 2016 12:19:51 GMT
Added camel-xstream 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/879fa603
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/879fa603
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/879fa603

Branch: refs/heads/master
Commit: 879fa6031660b589134ae3e08ba33f8b7a268c90
Parents: fc82672
Author: Andrea Cosentino <ancosen@gmail.com>
Authored: Thu Jun 9 13:06:29 2016 +0200
Committer: Andrea Cosentino <ancosen@gmail.com>
Committed: Thu Jun 9 13:06:29 2016 +0200

----------------------------------------------------------------------
 .../camel-xstream/src/main/docs/xstream.adoc    | 124 +++++++++++++++++++
 docs/user-manual/en/SUMMARY.md                  |   1 +
 2 files changed, 125 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/camel/blob/879fa603/components/camel-xstream/src/main/docs/xstream.adoc
----------------------------------------------------------------------
diff --git a/components/camel-xstream/src/main/docs/xstream.adoc b/components/camel-xstream/src/main/docs/xstream.adoc
new file mode 100644
index 0000000..14ce541
--- /dev/null
+++ b/components/camel-xstream/src/main/docs/xstream.adoc
@@ -0,0 +1,124 @@
+[[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-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.*"/>
+        ...
+
+-------------------------------------------------------------------

http://git-wip-us.apache.org/repos/asf/camel/blob/879fa603/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index 4377518..209a5dc 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -302,6 +302,7 @@
     * [XML Beans](xmlbeans.adoc)
     * [XML JSON](xmljson.adoc)
     * [XML Rpc](xmlrpc.adoc)
+    * [XStream](xstream.adoc)
     * [YAML](yaml.adoc)
 
 * User Guide


Mime
View raw message