= BeanIO DataFormat
:doctitle: BeanIO
:shortname: beanio
:artifactid: camel-beanio
:description: Marshal and unmarshal Java beans to and from flat files (such as CSV, delimited, or fixed length formats).
:since: 2.10
:supportlevel: Stable
:tabs-sync-option:
//Manually maintained attributes
:camel-spring-boot-name: beanio

*Since Camel {since}*

The BeanIO Data Format uses
https://beanio.github.io/[BeanIO] to handle flat payloads (such as XML, CSV,
delimited, or fixed length formats).

BeanIO is configured using a mapping XML file where you define the mapping from the flat format to Objects
(POJOs). This mapping file is mandatory to use.

== Options

// dataformat options: START
include::partial$dataformat-options.adoc[]
// dataformat options: END

== Usage

An example of a
https://github.com/apache/camel/blob/main/components/camel-beanio/src/test/resources/org/apache/camel/dataformat/beanio/mappings.xml[mapping
file is here].

To use the `BeanIODataFormat` you need to configure the data format with the mapping file, as well the name of the stream.

This can be done as shown below. The streamName is `employeeFile`.

[tabs]
====
Java::
+
[source,java]
----
DataFormat format = new BeanIODataFormat(
        "org/apache/camel/dataformat/beanio/mappings.xml",
        "employeeFile");

// a route which uses the bean io data format to format the CSV data
// to java objects
from("direct:unmarshal")
        .unmarshal(format)
        // and then split the message body, so we get a message for each row
        .split(body())
        .to("mock:beanio-unmarshal");

// convert a list of java objects back to flat format
from("direct:marshal")
        .marshal(format)
        .to("mock:beanio-marshal");
----

XML::
+
[source,xml]
----
<route>
    <from uri="direct:unmarshal"/>
    <unmarshal>
        <beanio mapping="org/apache/camel/dataformat/beanio/mappings.xml" streamName="employeeFile"/>
    </unmarshal>
    <split>
        <simple>${body}</simple>
        <to uri="mock:beanio-unmarshal"/>
    </split>
</route>

<route>
    <from uri="direct:marshal"/>
    <marshal>
        <beanio mapping="org/apache/camel/dataformat/beanio/mappings.xml" streamName="employeeFile"/>
    </marshal>
    <to uri="mock:beanio-marshal"/>
</route>
----
To use the BeanIO data format in XML, you need to configure it using the
`<beanio>` XML tag as shown below. The routes are similar to the example above.
====

The first route is for transforming CSV data into a `List<Employee>` Java objects.
Which we then split, so the mock endpoint receives a message for each row.

The second route is for the reverse operation, to transform a `List<Employee>` into a stream of CSV data.

The CSV data could, for example, be as below:

[source,text]
----
Joe,Smith,Developer,75000,10012009
Jane,Doe,Architect,80000,01152008
Jon,Anderson,Manager,85000,03182007
----

== Configuring beanio

The beanio mapper can be configured in `beanio.properties` file which can be loaded in the root classpath (in `src/main/resources` in your source projects).
See the https://beanio.github.io/docs/reference-guide#80-configuration[beanio documentation] for what can be configured.

NOTE: This configuration is global for beanio

== Dependencies

To use BeanIO in your Camel routes, you need to add a dependency on
*camel-beanio* which implements this data format.

If you use Maven, you can 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-beanio</artifactId>
  <version>4.4.0</version>
</dependency>
---------------------------------------


include::spring-boot:partial$starter.adoc[]
