[[univocity-fixed-dataformat]]
= uniVocity Fixed Length DataFormat
:docTitle: uniVocity Fixed Length
:artifactId: camel-univocity-parsers
:description: Marshal and unmarshal Java objects from and to fixed length records using UniVocity Parsers.
:since: 2.15
:supportLevel: Stable
include::{cq-version}@camel-quarkus:ROOT:partial$reference/dataformats/univocity-fixed.adoc[opts=optional]

*Since Camel {since}*

This xref:manual::data-format.adoc[Data
Format] uses https://www.univocity.com/pages/univocity_parsers_tutorial.html[uniVocity-parsers]
for reading and writing 3 kinds of tabular data text files:

* CSV (Comma Separated Values), where the values are separated by a
symbol (usually a comma)
* fixed-width, where the values have known sizes
* TSV (Tabular Separated Values), where the fields are separated by a
tabulation

Thus there are 3 data formats based on uniVocity-parsers.

If you use Maven you can just add the following to your pom.xml,
substituting the version number for the latest and greatest release.

[source,xml]
----------------------------------------------------
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-univocity-parsers</artifactId>
    <version>x.x.x</version>
</dependency>
----------------------------------------------------

== Options

Most configuration options of the uniVocity-parsers are available in the
data formats. If you want more information about a particular option,
please refer to their
https://www.univocity.com/pages/univocity_parsers_tutorial#settings[documentation
page].

The 3 data formats share common options and have dedicated ones, this
section presents them all.

== Options


// dataformat options: START
The uniVocity Fixed Length dataformat supports 16 options, which are listed below.



[width="100%",cols="2s,1m,1m,6",options="header"]
|===
| Name | Default | Java Type | Description
| skipTrailingCharsUntilNewline | false | Boolean | Whether or not the trailing characters until new line must be ignored. The default value is false
| recordEndsOnNewline | false | Boolean | Whether or not the record ends on new line. The default value is false
| padding |  | String | The padding character. The default value is a space
| nullValue |  | String | The string representation of a null value. The default value is null
| skipEmptyLines | true | Boolean | Whether or not the empty lines must be ignored. The default value is true
| ignoreTrailingWhitespaces | true | Boolean | Whether or not the trailing white spaces must ignored. The default value is true
| ignoreLeadingWhitespaces | true | Boolean | Whether or not the leading white spaces must be ignored. The default value is true
| headersDisabled | false | Boolean | Whether or not the headers are disabled. When defined, this option explicitly sets the headers as null which indicates that there is no header. The default value is false
| headerExtractionEnabled | false | Boolean | Whether or not the header must be read in the first line of the test document The default value is false
| numberOfRecordsToRead |  | Integer | The maximum number of record to read.
| emptyValue |  | String | The String representation of an empty value
| lineSeparator |  | String | The line separator of the files The default value is to use the JVM platform line separator
| normalizedLineSeparator | \n | String | The normalized line separator of the files The default value is a new line character.
| comment | # | String | The comment symbol. The default value is #
| lazyLoad | false | Boolean | Whether the unmarshalling should produce an iterator that reads the lines on the fly or if all the lines must be read at one. The default value is false
| asMap | false | Boolean | Whether the unmarshalling should produce maps for the lines values instead of lists. It requires to have header (either defined or collected). The default value is false
|===
// dataformat options: END



== Marshalling usages

The marshalling accepts either:

* A list of maps (`List<Map<String, ?>>`), one for each line
* A single map (`Map<String, ?>`), for a single line

Any other body will throws an exception.

=== Usage example: marshalling a Map into CSV format

[source,xml]
------------------------------------------------------------------------------------------------------------------------------------------------------------------------
<route>
    <from uri="direct:input"/>
    <marshal>
        <univocity-csv/>
    </marshal>
    <to uri="mock:result"/>
</route>
------------------------------------------------------------------------------------------------------------------------------------------------------------------------

=== Usage example: marshalling a Map into fixed-width format

[source,xml]
------------------------------------------------------------------------------------------------------------------------------------------------------------------------
<route>
    <from uri="direct:input"/>
    <marshal>
        <univocity-fixed padding="_">
            <univocity-header length="5"/>
            <univocity-header length="5"/>
            <univocity-header length="5"/>
        </univocity-fixed>
    </marshal>
    <to uri="mock:result"/>
</route>
------------------------------------------------------------------------------------------------------------------------------------------------------------------------

=== Usage example: marshalling a Map into TSV format

[source,xml]
------------------------------------------------------------------------------------------------------------------------------------------------------------------------
<route>
    <from uri="direct:input"/>
    <marshal>
        <univocity-tsv/>
    </marshal>
    <to uri="mock:result"/>
</route>
------------------------------------------------------------------------------------------------------------------------------------------------------------------------

== Unmarshalling usages

The unmarshalling uses an `InputStream` in order to read the data.

Each row produces either:

* a list with all the values in it (`asMap` option with `false`);
* A map with all the values indexed by the
headers (`asMap` option with `true`).

All the rows can either:

* be collected at once into a list (`lazyLoad` option with `false`);
* be read on the fly using an iterator (`lazyLoad` option with `true`).

=== Usage example: unmarshalling a CSV format into maps with automatic headers

[source,xml]
------------------------------------------------------------------------------------------------------------------------------------------------------------------------
<route>
    <from uri="direct:input"/>
    <unmarshal>
        <univocity-csv headerExtractionEnabled="true" asMap="true"/>
    </unmarshal>
    <to uri="mock:result"/>
</route>
------------------------------------------------------------------------------------------------------------------------------------------------------------------------

=== Usage example: unmarshalling a fixed-width format into lists

[source,xml]
------------------------------------------------------------------------------------------------------------------------------------------------------------------------
<route>
    <from uri="direct:input"/>
    <unmarshal>
        <univocity-fixed>
            <univocity-header length="5"/>
            <univocity-header length="5"/>
            <univocity-header length="5"/>
        </univocity-fixed>
    </unmarshal>
    <to uri="mock:result"/>
</route>
------------------------------------------------------------------------------------------------------------------------------------------------------------------------

include::camel-spring-boot::page$univocity-parsers-starter.adoc[]
