docs/components/modules/ROOT/pages/yaml-snakeyaml-dataformat.adoc

[[yaml-snakeyaml-dataformat]]
= YAML SnakeYAML DataFormat
:page-source: components/camel-snakeyaml/src/main/docs/yaml-snakeyaml-dataformat.adoc

*Available as of Camel version 2.17*

YAML is a Data Format to marshal and unmarshal
Java objects to and from http://www.yaml.org/[YAML].

For YAML to object marshalling, Camel provides integration with three
popular YAML libraries:

* The http://www.snakeyaml.org/[SnakeYAML] library

Every library requires adding the special camel component (see
"Dependency..." paragraphs further down). By default Camel uses the
SnakeYAML library.

== YAML Options

// dataformat options: START
The YAML SnakeYAML dataformat supports 11 options, which are listed below.



[width="100%",cols="2s,1m,1m,6",options="header"]
|===
| Name | Default | Java Type | Description
| library | SnakeYAML | YAMLLibrary | Which yaml library to use. By default it is SnakeYAML
| unmarshalTypeName |  | String | Class name of the java type to use when unarmshalling
| constructor |  | String | BaseConstructor to construct incoming documents.
| representer |  | String | Representer to emit outgoing objects.
| dumperOptions |  | String | DumperOptions to configure outgoing objects.
| resolver |  | String | Resolver to detect implicit type
| useApplicationContextClassLoader | true | Boolean | Use ApplicationContextClassLoader as custom ClassLoader
| prettyFlow | false | Boolean | Force the emitter to produce a pretty YAML document when using the flow style.
| allowAnyType | false | Boolean | Allow any class to be un-marshaled
| typeFilter |  | List | Set the types SnakeYAML is allowed to un-marshall
| 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

When using Spring Boot make sure to use the following Maven dependency to have support for auto configuration:

[source,xml]
----
<dependency>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-snakeyaml-starter</artifactId>
  <version>x.x.x</version>
  <!-- use the same version as your Camel core version -->
</dependency>
----


The component supports 10 options, which are listed below.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *camel.dataformat.yaml-snakeyaml.allow-any-type* | Allow any class to be un-marshaled | false | Boolean
| *camel.dataformat.yaml-snakeyaml.constructor* | BaseConstructor to construct incoming documents. |  | String
| *camel.dataformat.yaml-snakeyaml.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.yaml-snakeyaml.dumper-options* | DumperOptions to configure outgoing objects. |  | String
| *camel.dataformat.yaml-snakeyaml.enabled* | Enable yaml-snakeyaml dataformat | true | Boolean
| *camel.dataformat.yaml-snakeyaml.pretty-flow* | Force the emitter to produce a pretty YAML document when using the flow style. | false | Boolean
| *camel.dataformat.yaml-snakeyaml.representer* | Representer to emit outgoing objects. |  | String
| *camel.dataformat.yaml-snakeyaml.resolver* | Resolver to detect implicit type |  | String
| *camel.dataformat.yaml-snakeyaml.unmarshal-type-name* | Class name of the java type to use when unarmshalling |  | String
| *camel.dataformat.yaml-snakeyaml.use-application-context-class-loader* | Use ApplicationContextClassLoader as custom ClassLoader | true | Boolean
|===
// spring-boot-auto-configure options: END

WARNING: SnakeYAML can load any class from YAML definition which may lead to security breach so by default, SnakeYAML DataForma restrict the object it can load to standard Java objects like List or Long. If you want to load custom POJOs you need to add theirs type to SnakeYAML DataFormat type filter list. If your source is trusted, you can set the property allowAnyType to true so SnakeYAML DataForma won't perform any filter on the types.

== Using YAML data format with the SnakeYAML library

- Turn Object messages into yaml then send to MQSeries
+
[source,java]
------------------------------------------------------------
from("activemq:My.Queue")
  .marshal().yaml()
  .to("mqseries:Another.Queue");
------------------------------------------------------------
+
[source,java]
------------------------------------------------------------
from("activemq:My.Queue")
  .marshal().yaml(YAMLLibrary.SnakeYAML)
  .to("mqseries:Another.Queue");
------------------------------------------------------------

- Restrict classes to be loaded from YAML
+
[source,java]
------------------------------------------------------------
// Creat a SnakeYAMLDataFormat instance
SnakeYAMLDataFormat yaml = new SnakeYAMLDataFormat();

// Restrict classes to be loaded from YAML
yaml.addTypeFilters(TypeFilters.types(MyPojo.class, MyOtherPojo.class));

from("activemq:My.Queue")
  .unmarshal(yaml)
  .to("mqseries:Another.Queue");
------------------------------------------------------------

== Using YAML in Spring DSL

When using 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 YAML data format with the id snake and that it should use
    the TestPojo as the class type when doing unmarshal. The unmarshalTypeName
    is optional
  -->
  <yaml
    id="snake"
    library="SnakeYAML"
    unmarshalTypeName="org.apache.camel.component.yaml.model.TestPojo"/>

  <!--
    here we define a YAML data format with the id snake-safe which restricts the
    classes to be loaded from YAML to TestPojo and those belonging to package
    com.mycompany
  -->
  <yaml id="snake-safe">
    <typeFilter value="org.apache.camel.component.yaml.model.TestPojo"/>
    <typeFilter value="com.mycompany\..*" type="regexp"/>
  </yaml>
</dataFormats>
--------------------------------------------------------------------------------

And then you can refer to those ids in the route:

[source,xml]
-------------------------------------
  <route>
    <from uri="direct:unmarshal"/>
    <unmarshal>
      <custom ref="snake"/>
    </unmarshal>
    <to uri="mock:unmarshal"/>
  </route>
  <route>
    <from uri="direct:unmarshal-safe"/>
    <unmarshal>
      <custom ref="snake-safe"/>
    </unmarshal>
    <to uri="mock:unmarshal-safe"/>
  </route>
-------------------------------------


== Dependencies for SnakeYAML

To use YAML in your camel routes you need to add the a dependency
on *camel-snakeyaml* 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 the download page for the latest versions).

[source,xml]
------------------------------------------
<dependency>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-snakeyaml</artifactId>
  <version>${camel-version}</version>
</dependency>
------------------------------------------