pfx-filepreview Component

Overview

The pfx-filepreview component generates structured previews of CSV and XLSX files. It reads a configurable number of rows, auto-detects column types (STRING, NUMBER, INTEGER, BOOLEAN, DATE, DATE_TIME), and returns a JSON preview (or base64-encoded CSV when resultAsBase64=true). Supports compressed (ZIP), base64-encoded, and plain inputs.

URI pattern: pfx-filepreview:preview[?options]

Method

Parameters

Output Headers

Charset Resolution

With checkUtf=false (the default) the charset is the specifiedCharset when the caller set a usable one, and the auto-detected encoding otherwise. This is the behavior of every existing route.

With checkUtf=true the component is UTF-8 first. After the input is normalized — .gz/.zip decompressed — the content is validated as UTF-8 and the answer is reported in FilePreviewIsUtf. The charset is then picked in this order (first match wins):

1. specifiedCharset, when it is set to an encoding the JVM knows. The caller stays in control.

2. UTF-8, when FilePreviewIsUtf is true. No detection runs at all — the verdict is deterministic, so there is nothing left to guess.

3. Auto-detection, when FilePreviewIsUtf is false. The encoding is detected from the content, as before.

The verdict covers the entire file, not only the previewed rows: one invalid byte in the last row of a 2 GB file makes it false. The check therefore reads the input to its end, in 8 KB chunks and with no extra memory — and in the same single pass that counts the records when returnTotalNumberOfRecords=true. This is the reason the check is opt-in: a preview that leaves checkUtf at its default still reads only the bytes it needs.

The verdict is taken on the decompressed bytes, so a UTF-8 CSV inside a ZIP archive is true.

A base64 input never produces a verdict. With inputBase64Encoded=true the body is a snippet the client sent back, not the file, so a verdict over it would describe the snippet while claiming to describe the file. On that pathway the check is skipped whatever checkUtf says, no FilePreviewIsUtf header is set, and the charset is resolved the usual way — specifiedCharset, else auto-detection.

Auto-detection is a heuristic and can pick the wrong single-byte encoding for short content — supply specifiedCharset when the source encoding is known and is not UTF-8.

Output Format

{
  "fileName": "products.csv",
  "columns": [
    {
      "name": "sku",
      "type": "STRING",
      "order": 0,
      "parsedValues": ["SKU001", "SKU002", "SKU003"],
      "originalValues": ["SKU001", "SKU002", "SKU003"]
    },
    {
      "name": "price",
      "type": "NUMBER",
      "order": 1,
      "parsedValues": [29.99, 149.50, 89.00],
      "originalValues": ["29.99", "149.50", "89.00"]
    }
  ]
}

With resultAsBase64=true the result is not this JSON structure but base64-encoded CSV text (header row + up to maxRecords rows). For XLSX inputs the parsed rows are serialized to CSV, so the preview is consistent with FilePreviewType=CSV.

Examples

Preview CSV from inbound directory

<routes xmlns="http://camel.apache.org/schema/spring">
    <route id="previewCsv">
        <from uri="file:{{inbound.path}}?{{archive.file}}&amp;{{read.lock}}"/>
        <to uri="pfx-filepreview:preview?fileType=CSV&amp;maxRecords=5"/>
        <log message="Preview: ${body}"/>
    </route>
</routes>

Preview XLSX, store result in header (preserve body)

<to uri="pfx-filepreview:preview?fileType=XLSX&amp;maxRecords=3&amp;storeResultTo=header&amp;storeResultToName=previewJson"/>
<!-- body still contains original file; header.previewJson has the JSON -->

European CSV (semicolon delimiter, comma decimal)

<to uri="pfx-filepreview:preview?fileType=CSV&amp;separator=;&amp;decimalSeparator=,&amp;dateFormat=dd.MM.yyyy"/>

Preview with a UTF-8 verdict

<to uri="pfx-filepreview:preview?fileType=CSV&amp;maxRecords=5&amp;checkUtf=true"/>
<log message="Valid UTF-8: ${header.FilePreviewIsUtf}"/>

Base64 input/output (for API transport)

<to uri="pfx-filepreview:preview?fileType=CSV&amp;inputBase64Encoded=true&amp;resultAsBase64=true"/>

Column Type Detection

Types are detected in this precedence order (first match wins):

Empty values are ignored during type detection. A column with all-empty values defaults to STRING.

Common Pitfalls

• fileType is required — the component does not auto-detect file format.

• ZIP-compressed files are decompressed automatically — no special configuration needed.

• When storeResultTo=header, you must also set storeResultToName.

• Keep maxRecords low (≤20) for preview use cases — the component reads the full file for type detection but stops collecting rows after maxRecords.

• For XLSX, the first sheet (index 0) is always used.