...
Streams are caching in memory. In Camel 2.0, large stream messages (over 64 Kb in Camel 2.11 or older, and 128 kb from Camel 2.12 onwards) will be cached in a temporary file instead – Camel itself will handle deleting the temporary file once the cached stream is no longer necessary.
...
Info | ||
---|---|---|
| ||
The StreamCache will affect your payload object as it will replace the Stream payload with a However to not change the payload under the covers without the end user really knowing we changed the default in Camel 2.0 to disabled. So in Camel 2.0 you have to explicit enable it if you want to use it. |
Tip |
---|
If using Camel 2.12 onwards then see about StreamCachingStrategy further below which is the recommended way to configure stream caching options. |
Enabling stream caching
In Apache Camel, you can explicitly enable stream caching for a single route with the streamCaching
DSL method:
...
Code Block | ||||
---|---|---|---|---|
| ||||
<camelContext streamCache="true"> <route> <from uri="jbi:service:http://foo.bar.org/MyService"/> <to uri="jbi:service:http://foo.bar.org/MyOtherService"/> </route> <route streamCache="false"> <from uri="jms:queue:foo"/> <to uri="jms:queue:bar"/> </route> </camelContext> |
Enabling from Java DSL
In Camel 2.0 you You can enable stream cache by setting the property on CamelContext, for instance in a RouteBuilder class:
...
Code Block | ||||
---|---|---|---|---|
| ||||
context.setStreamCache(true); from("jetty:http://0.0.0.0:9090").noStreamCaching() .to("file:target/incoming"); |
Implicitly enabled for multicast and dead letter channel (Camel 1.x)
Some EIPs require that the message content can be read multiple times. Stream caching will be automatically enabled when using these EIPs in your routes:
...
Streaming cache to files
When stream cache is enabled it will by default spool big streams to files instead of keeping them in memory. The default threshold is 64kb but you can configure it with the following properties:
Property | Default | Description |
---|---|---|
CamelCachedOutputStreamBufferSize | 2kb | Camel 2.9.4, 2.10.2, 2.11.0: Size in bytes of the buffer used in the stream. |
CamelCachedOutputStreamThreshold | 64kb or 128kb | 64kb for Camel 2.11 or older. 128kb for Camel 2.12 onwards. Size in bytes when the stream should be spooled to disk instead of keeping in memory. Use a value of 0 or negative to disable it all together so streams is always kept in memory regardless of their size. |
CamelCachedOutputStreamOutputDirectory | java.io.tmpdir | Base directory where temporary files for spooled streams should be stored. |
CamelCachedOutputStreamCipherTransformation | null | Camel 2.11.0: If set, the temporary files are encrypted using the specified cipher transformation (i.e., a valid stream or 8-bit cipher name such as "RC4", "AES/CTR/NoPadding". An empty name "" is treated as null). |
You set these properties on the CamelContext as shown below, where we use a 1mb threshold to spool to disk for messages bigger than 1mb:
Code Block | ||||
---|---|---|---|---|
| ||||
context.getProperties().put(CachedOutputStream.TEMP_DIR, "/tmp/cachedir"); context.getProperties().put(CachedOutputStream.THRESHOLD, "10241048576"); context.getProperties().put(CachedOutputStream.BUFFER_SIZE, "4096131072"); // to enable encryption using RC4 // context.getProperties().put(CachedOutputStream.CIPHER_TRANSFORMATION, "RC4"); |
And in XML you do
Code Block | ||||
---|---|---|---|---|
| ||||
<camelContext xmlns="http://camel.apache.org/schema/blueprint">
<!-- disable stream caching spool to disk -->
<properties>
<property key="CamelCachedOutputStreamOutputDirectory" value="/tmp/cachedir"/>
<property key="CamelCachedOutputStreamThreshold" value="1048576"/>
<property key="CamelCachedOutputStreamBufferSize" value="131072"/>
</properties>
|
Disabling spooling to disk
Available as of *Camel 1.6.2/2.0
You can disable spooling to disk by setting a threshold of 0 or a negative value.
Code Block |
---|
// disable spooling to disk
context.getProperties().put(CachedOutputStream.THRESHOLD, "-1");
|
And in XML you do
Code Block | ||||
---|---|---|---|---|
| ||||
<camelContext xmlns="http://camel.apache.org/schema/blueprint"> <!-- disable stream caching spool to disk --> <properties> <property key="CamelCachedOutputStreamThreshold" value="-1"/> </properties> |
Using StreamCachingStrategy
Available as of Camel 2.12
Stream caching is from Camel 2.12 onwards intended to be configured using org.apache.camel.spi.StreamCachingStrategy
.
The old kind of configuration using properties on the CamelContext has been marked as deprecated.
The strategy has the following options:
Option | Default | Description |
---|---|---|
| | Base directory where temporary files for spooled streams should be stored. This option supports naming patterns as documented below. |
| | If set, the temporary files are encrypted using the specified cipher transformation (i.e., a valid stream or 8-bit cipher name such as "RC4", "AES/CTR/NoPadding". An empty name "" is treated as null). |
| | Size in bytes when the stream should be spooled to disk instead of keeping in memory. Use a value of 0 or negative to disable it all together so streams is always kept in memory regardless of their size. |
| | A percentage (1 to 99) of current used heap memory to use as threshold for spooling streams to disk. The upper bounds is based on heap committed (guaranteed memory the JVM can claim). This can be used to spool to disk when running low on memory. |
| | If |
| | Whether any or all |
| | Initial size if in-memory created stream buffers. |
| | Whether to remove the spool directory when stopping CamelContext. |
| | Whether utilization statistics is enabled. By enabling this you can see these statics for example with JMX. |
SpoolDirectory naming pattern
The following patterns is supported:
- #uuid# = a random UUID
- #camelId# = the CamelContext id (eg the name)
- #name# - same as #camelId#
- #counter# - an incrementing counter
- #bundleId# - the OSGi bundle id (only for OSGi environments)
- #symbolicName# - the OSGi symbolic name (only for OSGi environments)
- #version# - the OSGi bundle version (only for OSGi environments)
- ${env:key} - the environment variable with the key
- ${key} - the JVM system property with the key
A could of examples, to store in the java temp directory with a sub directory using the CamelContext name:
Code Block |
---|
context.getStreamCachingStrategy().setSpoolDirectory"${java.io.tmpdir}#name#/");
|
To store in KARAF_HOME/tmp/bundleId directory
Code Block |
---|
context.getStreamCachingStrategy().setSpoolDirectory"${env:KARAF_HOME}/tmp/bundle#bundleId#");
|
Using StreamCachingStrategy in Java
You can configure the StreamCachingStrategy
in Java as shown below:
Code Block |
---|
context.getStreamCachingStrategy().setSpoolDirectory"/tmp/cachedir");
context.getStreamCachingStrategy().setSpoolThreshold(64 * 1024);
context.getStreamCachingStrategy().setBufferSize(16 * 1024);
// to enable encryption using RC4
// context.getStreamCachingStrategy().setSpoolChiper("RC4");
|
And remember to enable Stream caching on the CamelContext or on routes
Code Block |
---|
context.setStreamCaching(true);
|
Using StreamCachingStrategy in XML
And in XML you do:
Code Block | ||||
---|---|---|---|---|
| ||||
<camelContext streamCache="true" xmlns="http://camel.apache.org/schema/blueprint">
<streamCaching id="myCacheConfig" bufferSize="16384" spoolDirectory="/tmp/cachedir" spoolThreshold="65536"/>
<route>
<from uri="direct:c"/>
<to uri="mock:c"/>
</route>
</camelContext>
|
You can also define a <bean> instead of using the <streamCaching> tag:
And in XML you do
Code Block | ||||
---|---|---|---|---|
| ||||
<!-- define a bean of type StreamCachingStrategy which CamelContext will automatic use -->
<bean id="streamStrategy" class="org.apache.camel.impl.DefaultStreamCachingStrategy">
<property name="spoolDirectory" value="/tmp/cachedir"/>
<property name="spoolThreshold" value="65536"/>
<property name="bufferSize" value="16384"/>
</bean>
<!-- remember to enable stream caching -->
<camelContext streamCaching="true" xmlns="http://camel.apache.org/schema/spring">
|
Using spoolUsedHeapMemoryThreshold
By default stream caching will spool only big payloads (128kb or bigger) to disk. However you can also set the spoolUsedHeapMemoryThreshold option which is a percentage of used heap memory. This can be used to also spool to disk when running low on memory.
For example with:
Code Block |
---|
<streamCaching id="myCacheConfig" spoolDirectory="/tmp/cachedir" spoolUsedHeapMemoryThreshold="70"/>
|
Then notice that as spoolThreshold is default enabled with 128kb, then we have both thresholds in use (spoolThreshold and spoolUsedHeapMemoryThreshold). And in this example then we only spool to disk if payload is > 128kb and that used heap memory is > 70%. The reason is that we have the option anySpoolRules
as default false
. That means both rules must be true
(eg AND).
If we want to spool to disk if either of the rules (eg OR), then we can do:
Code Block |
---|
<streamCaching id="myCacheConfig" spoolDirectory="/tmp/cachedir" spoolUsedHeapMemoryThreshold="70" anySpoolRules="true"/>
|
If we only want to spool to disk if we run low on memory then we can set:
Code Block |
---|
<streamCaching id="myCacheConfig" spoolDirectory="/tmp/cachedir" spoolThreshold="-1" spoolUsedHeapMemoryThreshold="70"/>
|
... then we do not use the spoolThreshold rule, and only the heap memory based is in use.
By default the upper limit of the used heap memory is based on the maximum heap size. Though you can also configure to use the committed heap size as the upper limit, this is done using the spoolUsedHeapMemoryThreshold
option as shown below:
Code Block |
---|
<streamCaching id="myCacheConfig" spoolDirectory="/tmp/cachedir" spoolUsedHeapMemoryThreshold="70" spoolUsedHeapMemoryLimit="Committed"/> |
Using custom SpoolRule implementations
You can implement your custom rules to determine if the stream should be spooled to disk. This can be done by implementing the interface org.apache.camel.spi.StreamCachingStrategy.SpoolRule
which has a single method:
Code Block |
---|
boolean shouldSpoolCache(long length); |
The length is the length of the stream.
To use the rule then add it to the StreamCachingStrategy
as shown below:
Code Block |
---|
SpoolRule mySpoolRule = ...
context.getStreamCachingStrategy().addSpoolRule(mySpoolRule);
|
And from XML you need to define a <bean> with your custom rule
Code Block | ||||
---|---|---|---|---|
| ||||
<bean id="mySpoolRule" class="com.foo.MySpoolRule"/>
<streamCaching id="myCacheConfig" spoolDirectory="/tmp/cachedir" spoolRules="mySpoolRule"/>
|
Using the spoolRules
attribute on <streamCaching>. if you have more rules, then separate them by comma.
Code Block | ||||
---|---|---|---|---|
| ||||
<streamCaching id="myCacheConfig" spoolDirectory="/tmp/cachedir" spoolRules="mySpoolRule,myOtherSpoolRule"/>
|
How it works?
In order to determine if a type requires caching, we leverage the type converter feature. Any type that requires stream caching can be converted into an org.apache.camel.StreamCache
instance.