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 <anco...@gmail.com> Authored: Thu Jun 9 13:06:29 2016 +0200 Committer: Andrea Cosentino <anco...@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
