<commit_before>[[xstream-dataformat]]
== XStream DataFormat

*Available as of Camel version 1.3*

XStream is a 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>
----------------------------------------------------------

### Options

// dataformat options: START
The XStream dataformat supports 10 options, which are listed below.



[width="100%",cols="2s,1m,1m,6",options="header"]
|===
| Name | Default | Java Type | Description
| 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.
| encoding |  | String | Sets the encoding to use
| driver |  | String | To use a custom XStream driver. The instance must be of type com.thoughtworks.xstream.io.HierarchicalStreamDriver
| driverRef |  | String | To refer to a custom XStream driver to lookup in the registry. The instance must be of type com.thoughtworks.xstream.io.HierarchicalStreamDriver
| mode |  | String | Mode for dealing with duplicate references The possible values are: NO_REFERENCES ID_REFERENCES XPATH_RELATIVE_REFERENCES XPATH_ABSOLUTE_REFERENCES SINGLE_NODE_XPATH_RELATIVE_REFERENCES SINGLE_NODE_XPATH_ABSOLUTE_REFERENCES
| converters |  | List | List of class names for using custom XStream converters. The classes must be of type com.thoughtworks.xstream.converters.Converter
| aliases |  | Map | Alias a Class to a shorter name to be used in XML elements.
| omitFields |  | Map | Prevents a field from being serialized. To omit a field you must always provide the declaring type and not necessarily the type that is converted.
| implicitCollections |  | Map | Adds a default implicit collection which is used for any unmapped XML tag.
| contentTypeHeader | false | Boolean | Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc.
|===
// dataformat options: END
// spring-boot-auto-configure options: START
=== Spring Boot Auto-Configuration


The component supports 31 options, which are listed below.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *camel.dataformat.json-xstream.allow-jms-type* | Used for JMS users to allow the JMSType header from the JMS spec to specify a FQN classname to use to unmarshal to. | false | Boolean
| *camel.dataformat.json-xstream.allow-unmarshall-type* | If enabled then Jackson is allowed to attempt to use the CamelJacksonUnmarshalType header during the unmarshalling. This should only be enabled when desired to be used. | false | Boolean
| *camel.dataformat.json-xstream.collection-type-name* | 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. |  | String
| *camel.dataformat.json-xstream.content-type-header* | Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc. | false | Boolean
| *camel.dataformat.json-xstream.disable-features* | 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 |  | String
| *camel.dataformat.json-xstream.enable-features* | 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 |  | String
| *camel.dataformat.json-xstream.enable-jaxb-annotation-module* | Whether to enable the JAXB annotations module when using jackson. When enabled then JAXB annotations can be used by Jackson. | false | Boolean
| *camel.dataformat.json-xstream.enabled* | Enable json-xstream dataformat | true | Boolean
| *camel.dataformat.json-xstream.include* | 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 NON_NULL |  | String
| *camel.dataformat.json-xstream.json-view* | 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 |  | Class
| *camel.dataformat.json-xstream.library* | Which json library to use. |  | JsonLibrary
| *camel.dataformat.json-xstream.module-class-names* | 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. |  | String
| *camel.dataformat.json-xstream.module-refs* | To use custom Jackson modules referred from the Camel registry. Multiple modules can be separated by comma. |  | String
| *camel.dataformat.json-xstream.object-mapper* | Lookup and use the existing ObjectMapper with the given id when using Jackson. |  | String
| *camel.dataformat.json-xstream.permissions* | 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. |  | String
| *camel.dataformat.json-xstream.pretty-print* | To enable pretty printing output nicely formatted. Is by default false. | false | Boolean
| *camel.dataformat.json-xstream.timezone* | If set then Jackson will use the Timezone when marshalling/unmarshalling. This option will have no effect on the others Json DataFormat, like gson, fastjson and xstream. |  | String
| *camel.dataformat.json-xstream.unmarshal-type-name* | Class name of the java type to use when unarmshalling |  | String
| *camel.dataformat.json-xstream.use-default-object-mapper* | Whether to lookup and use default Jackson ObjectMapper from the registry. | true | Boolean
| *camel.dataformat.json-xstream.use-list* | To unarmshal to a List of Map or a List of Pojo. | false | Boolean
| *camel.dataformat.xstream.aliases* | Alias a Class to a shorter name to be used in XML elements. The option is a java.util.Map<java.lang.String,java.lang.String> type. |  | String
| *camel.dataformat.xstream.content-type-header* | Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc. | false | Boolean
| *camel.dataformat.xstream.converters* | List of class names for using custom XStream converters. The classes must be of type com.thoughtworks.xstream.converters.Converter |  | List
| *camel.dataformat.xstream.driver* | To use a custom XStream driver. The instance must be of type com.thoughtworks.xstream.io.HierarchicalStreamDriver |  | String
| *camel.dataformat.xstream.driver-ref* | To refer to a custom XStream driver to lookup in the registry. The instance must be of type com.thoughtworks.xstream.io.HierarchicalStreamDriver |  | String
| *camel.dataformat.xstream.enabled* | Enable xstream dataformat | true | Boolean
| *camel.dataformat.xstream.encoding* | Sets the encoding to use |  | String
| *camel.dataformat.xstream.implicit-collections* | Adds a default implicit collection which is used for any unmapped XML tag. The option is a java.util.Map<java.lang.String,java.lang.String[]> type. |  | String
| *camel.dataformat.xstream.mode* | Mode for dealing with duplicate references The possible values are: NO_REFERENCES ID_REFERENCES XPATH_RELATIVE_REFERENCES XPATH_ABSOLUTE_REFERENCES SINGLE_NODE_XPATH_RELATIVE_REFERENCES SINGLE_NODE_XPATH_ABSOLUTE_REFERENCES |  | String
| *camel.dataformat.xstream.omit-fields* | Prevents a field from being serialized. To omit a field you must always provide the declaring type and not necessarily the type that is converted. The option is a java.util.Map<java.lang.String,java.lang.String[]> type. |  | String
| *camel.dataformat.xstream.permissions* | 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. |  | String
|===
// spring-boot-auto-configure options: END
ND


### 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");
---------------------------------------------------------

### 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. <commit_msg>Fix xtream link<commit_after>[[xstream-dataformat]]
== XStream DataFormat

*Available as of Camel version 1.3*

XStream is a Data Format which uses the
http://x-stream.github.io/[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>
----------------------------------------------------------

### Options

// dataformat options: START
The XStream dataformat supports 10 options, which are listed below.



[width="100%",cols="2s,1m,1m,6",options="header"]
|===
| Name | Default | Java Type | Description
| 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.
| encoding |  | String | Sets the encoding to use
| driver |  | String | To use a custom XStream driver. The instance must be of type com.thoughtworks.xstream.io.HierarchicalStreamDriver
| driverRef |  | String | To refer to a custom XStream driver to lookup in the registry. The instance must be of type com.thoughtworks.xstream.io.HierarchicalStreamDriver
| mode |  | String | Mode for dealing with duplicate references The possible values are: NO_REFERENCES ID_REFERENCES XPATH_RELATIVE_REFERENCES XPATH_ABSOLUTE_REFERENCES SINGLE_NODE_XPATH_RELATIVE_REFERENCES SINGLE_NODE_XPATH_ABSOLUTE_REFERENCES
| converters |  | List | List of class names for using custom XStream converters. The classes must be of type com.thoughtworks.xstream.converters.Converter
| aliases |  | Map | Alias a Class to a shorter name to be used in XML elements.
| omitFields |  | Map | Prevents a field from being serialized. To omit a field you must always provide the declaring type and not necessarily the type that is converted.
| implicitCollections |  | Map | Adds a default implicit collection which is used for any unmapped XML tag.
| contentTypeHeader | false | Boolean | Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc.
|===
// dataformat options: END
// spring-boot-auto-configure options: START
=== Spring Boot Auto-Configuration


The component supports 31 options, which are listed below.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *camel.dataformat.json-xstream.allow-jms-type* | Used for JMS users to allow the JMSType header from the JMS spec to specify a FQN classname to use to unmarshal to. | false | Boolean
| *camel.dataformat.json-xstream.allow-unmarshall-type* | If enabled then Jackson is allowed to attempt to use the CamelJacksonUnmarshalType header during the unmarshalling. This should only be enabled when desired to be used. | false | Boolean
| *camel.dataformat.json-xstream.collection-type-name* | 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. |  | String
| *camel.dataformat.json-xstream.content-type-header* | Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc. | false | Boolean
| *camel.dataformat.json-xstream.disable-features* | 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 |  | String
| *camel.dataformat.json-xstream.enable-features* | 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 |  | String
| *camel.dataformat.json-xstream.enable-jaxb-annotation-module* | Whether to enable the JAXB annotations module when using jackson. When enabled then JAXB annotations can be used by Jackson. | false | Boolean
| *camel.dataformat.json-xstream.enabled* | Enable json-xstream dataformat | true | Boolean
| *camel.dataformat.json-xstream.include* | 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 NON_NULL |  | String
| *camel.dataformat.json-xstream.json-view* | 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 |  | Class
| *camel.dataformat.json-xstream.library* | Which json library to use. |  | JsonLibrary
| *camel.dataformat.json-xstream.module-class-names* | 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. |  | String
| *camel.dataformat.json-xstream.module-refs* | To use custom Jackson modules referred from the Camel registry. Multiple modules can be separated by comma. |  | String
| *camel.dataformat.json-xstream.object-mapper* | Lookup and use the existing ObjectMapper with the given id when using Jackson. |  | String
| *camel.dataformat.json-xstream.permissions* | 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. |  | String
| *camel.dataformat.json-xstream.pretty-print* | To enable pretty printing output nicely formatted. Is by default false. | false | Boolean
| *camel.dataformat.json-xstream.timezone* | If set then Jackson will use the Timezone when marshalling/unmarshalling. This option will have no effect on the others Json DataFormat, like gson, fastjson and xstream. |  | String
| *camel.dataformat.json-xstream.unmarshal-type-name* | Class name of the java type to use when unarmshalling |  | String
| *camel.dataformat.json-xstream.use-default-object-mapper* | Whether to lookup and use default Jackson ObjectMapper from the registry. | true | Boolean
| *camel.dataformat.json-xstream.use-list* | To unarmshal to a List of Map or a List of Pojo. | false | Boolean
| *camel.dataformat.xstream.aliases* | Alias a Class to a shorter name to be used in XML elements. The option is a java.util.Map<java.lang.String,java.lang.String> type. |  | String
| *camel.dataformat.xstream.content-type-header* | Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc. | false | Boolean
| *camel.dataformat.xstream.converters* | List of class names for using custom XStream converters. The classes must be of type com.thoughtworks.xstream.converters.Converter |  | List
| *camel.dataformat.xstream.driver* | To use a custom XStream driver. The instance must be of type com.thoughtworks.xstream.io.HierarchicalStreamDriver |  | String
| *camel.dataformat.xstream.driver-ref* | To refer to a custom XStream driver to lookup in the registry. The instance must be of type com.thoughtworks.xstream.io.HierarchicalStreamDriver |  | String
| *camel.dataformat.xstream.enabled* | Enable xstream dataformat | true | Boolean
| *camel.dataformat.xstream.encoding* | Sets the encoding to use |  | String
| *camel.dataformat.xstream.implicit-collections* | Adds a default implicit collection which is used for any unmapped XML tag. The option is a java.util.Map<java.lang.String,java.lang.String[]> type. |  | String
| *camel.dataformat.xstream.mode* | Mode for dealing with duplicate references The possible values are: NO_REFERENCES ID_REFERENCES XPATH_RELATIVE_REFERENCES XPATH_ABSOLUTE_REFERENCES SINGLE_NODE_XPATH_RELATIVE_REFERENCES SINGLE_NODE_XPATH_ABSOLUTE_REFERENCES |  | String
| *camel.dataformat.xstream.omit-fields* | Prevents a field from being serialized. To omit a field you must always provide the declaring type and not necessarily the type that is converted. The option is a java.util.Map<java.lang.String,java.lang.String[]> type. |  | String
| *camel.dataformat.xstream.permissions* | 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. |  | String
|===
// spring-boot-auto-configure options: END
ND


### 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");
---------------------------------------------------------

### XMLInputFactory and XMLOutputFactory

http://x-stream.github.io/[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. 
{'fraction_non_alphanumeric': 0.1016949152542373, 'fraction_numerical': 0.0020177562550443904, 'mean_word_length': 4.0153815017203, 'pattern_counts': {'":': 0, '<': 27, '<?xml version=': 0, '>': 27, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 44}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4739234', 'n_tokens_mistral': 6828, 'n_tokens_neox': 6503, 'n_words': 2798}