AIL Community

Camel Tip: Stream Cache for One-Time-Read Streams

Apache Camel often transports message bodies as streams, for example InputStream, Reader, or StreamSource. These types are efficient because they avoid loading the whole payload into memory immediately. The danger is that a stream is normally consumable only once. After one processor, logger, validator, or component reads it, the next step in the route may see an empty body.

Camel stream caching solves this by converting the stream into a re-readable cache. This allows the same message body to be read multiple times, which is important for logging, retries, content-based routing, validation, error handling, or any route where more than one processor needs access to the payload.

Stream caching can be enabled globally on the Camel context:

context.setStreamCaching(true);

It can also be enabled on a specific route:

from("file:inbox")
    .streamCache(true)
    .to("bean:foo");

In XML, it can be activated with:

<camelContext streamCache="true">
    <route streamCache="true">
        <from uri="file:inbox"/>
        <to uri="bean:foo"/>
    </route>
</camelContext>

In application properties, it can be configured with options such as:

camel.main.streamCachingEnabled=true

For large payloads, Camel can keep cached streams in memory or spool them to disk. Disk spooling is useful when payloads are large, but it must be configured carefully because it creates temporary files and may have security, performance, and cleanup implications.

The main risk appears when stream caching is disabled or misunderstood. A developer may log the body, inspect it in a processor, or convert it to a string, not realizing that this consumes the stream. Later in the route, the actual business processor receives an empty body. This can lead to confusing bugs, failed integrations, incomplete files, or lost request/response data.

The safe rule is simple: whenever a Camel route may read a stream body more than once, enable stream caching or explicitly convert the body into a reusable type. Only disable stream caching when you are certain the stream is consumed exactly once, such as when directly piping a large payload to a file or another streaming destination.

More posts