Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 18. BeanIO

Since Camel 2.10

The BeanIO Data Format uses 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.

18.1. Dependencies
Copy link

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

<dependency>
  <groupId>org.apache.camel.springboot</groupId>
  <artifactId>camel-beanio-starter</artifactId>
</dependency>
Copy to Clipboard Toggle word wrap

18.2. Options
Copy link

The BeanIO dataformat supports 8 options, which are listed below.

Expand
NameDefaultJava TypeDescription

mapping (common)

 

String

Required The BeanIO mapping file. Is by default loaded from the classpath. You can prefix with file:, http:, or classpath: to denote from where to load the mapping file.

streamName (common)

 

String

Required The name of the stream to use.

ignoreUnidentifiedRecords (common)

false

Boolean

Whether to ignore unidentified records.

ignoreUnexpectedRecords (common)

false

Boolean

Whether to ignore unexpected records.

ignoreInvalidRecords (common)

false

Boolean

Whether to ignore invalid records.

encoding (advanced)

 

String

The charset to use. Is by default the JVM platform default charset.

beanReaderErrorHandlerType (advanced)

 

String

To use a custom org.apache.camel.dataformat.beanio.BeanIOErrorHandler as error handler while parsing. Configure the fully qualified class name of the error handler. Notice the options ignoreUnidentifiedRecords, ignoreUnexpectedRecords, and ignoreInvalidRecords may not be in use when you use a custom error handler.

unmarshalSingleObject (advanced)

false

Boolean

This options controls whether to unmarshal as a list of objects or as a single object only. The former is the default mode, and the latter is only intended in special use-cases where beanio maps the Camel message to a single POJO bean.

18.3. Usage
Copy link

An example of a 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.

  • Java

  • XML 

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");
Copy to Clipboard Toggle word wrap 
<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>
Copy to Clipboard Toggle word wrap

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: 

Joe,Smith,Developer,75000,10012009
Jane,Doe,Architect,80000,01152008
Jon,Anderson,Manager,85000,03182007
Copy to Clipboard Toggle word wrap

18.4. Spring Boot Auto-Configuration
Copy link

The component supports 9 options, which are listed below.

Expand
NameDescriptionDefaultType

camel.dataformat.beanio.bean-reader-error-handler-type

To use a custom org.apache.camel.dataformat.beanio.BeanIOErrorHandler as error handler while parsing. Configure the fully qualified class name of the error handler. Notice the options ignoreUnidentifiedRecords, ignoreUnexpectedRecords, and ignoreInvalidRecords may not be in use when you use a custom error handler.

 

String

camel.dataformat.beanio.enabled

Whether to enable auto configuration of the beanio data format. This is enabled by default.

 

Boolean

camel.dataformat.beanio.encoding

The charset to use. Is by default the JVM platform default charset.

 

String

camel.dataformat.beanio.ignore-invalid-records

Whether to ignore invalid records.

false

Boolean

camel.dataformat.beanio.ignore-unexpected-records

Whether to ignore unexpected records.

false

Boolean

camel.dataformat.beanio.ignore-unidentified-records

Whether to ignore unidentified records.

false

Boolean

camel.dataformat.beanio.mapping

The BeanIO mapping file. Is by default loaded from the classpath. You can prefix with file:, http:, or classpath: to denote from where to load the mapping file.

 

String

camel.dataformat.beanio.stream-name

The name of the stream to use.

 

String

camel.dataformat.beanio.unmarshal-single-object

This option controls whether to unmarshal as a list of objects or as a single object only. The former is the default mode, and the latter is only intended in special use-cases where beanio maps the Camel message to a single POJO bean.

false

Boolean

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top