svn commit: r870587 - in /websites/production/camel/content: cache/main.pageCache stream-caching.html

[bu...@apache.org]

Author: buildbot
Date: Mon Jul 22 14:18:39 2013
New Revision: 870587

Log:
Production update by buildbot for camel

Modified:
    websites/production/camel/content/cache/main.pageCache
    websites/production/camel/content/stream-caching.html

Modified: websites/production/camel/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.

Modified: websites/production/camel/content/stream-caching.html
==============================================================================
--- websites/production/camel/content/stream-caching.html (original)
+++ websites/production/camel/content/stream-caching.html Mon Jul 22 14:18:39 2013
@@ -262,7 +262,7 @@ The old kind of configuration using prop
 <p>The strategy has the following options:</p>
 
 <div class="table-wrap">
-<table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"> Option </th><th colspan="1" rowspan="1" class="confluenceTh"> Default </th><th colspan="1" rowspan="1" class="confluenceTh"> Description </th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> <tt>spoolDirectory</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> <tt>${java.io.tmpdir}camel-tmp-#uuid#</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> Base directory where temporary files for spooled streams should be stored. This option supports naming patterns as documented below. </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> <tt>spoolThreshold</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> <tt>128kb</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> 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 reg
 ardless of their size. </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> <tt>spoolChiper</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> <tt>null</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> 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).</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> <tt>bufferSize</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> <tt>4096</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> Initial size if in-memory created stream buffers. </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> <tt>removeSpoolDirectoryWhenStopping</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> <tt>true</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> Whether to remove the spool directory when stopping <a shape="rect" href="cam
 elcontext.html" title="CamelContext">CamelContext</a>. </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> <tt>statisticsEnabled</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> <tt>false</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> Whether utilization statistics is enabled. By enabling this you can see these statics for example with JMX. </td></tr></tbody></table>
+<table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"> Option </th><th colspan="1" rowspan="1" class="confluenceTh"> Default </th><th colspan="1" rowspan="1" class="confluenceTh"> Description </th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> <tt>spoolDirectory</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> <tt>${java.io.tmpdir}camel-tmp-#uuid#</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> Base directory where temporary files for spooled streams should be stored. This option supports naming patterns as documented below. </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> <tt>spoolChiper</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> <tt>null</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> 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 tr
 eated as null).</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> <tt>spoolThreshold</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> <tt>128kb</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> 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. </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> <tt>spoolHeapMemoryWatermarkThreshold</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> <tt>0</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> 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. </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> <tt>anySpoolRules</tt> </td
 ><td colspan="1" rowspan="1" class="confluenceTd"> <tt>false</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> Whether any or all <tt>SpoolRule}}s must return {{true</tt> to determine if the stream should be spooled or not. This can be used as applying AND/OR binary logic to all the rules. By default its AND based. </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> <tt>bufferSize</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> <tt>4096</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> Initial size if in-memory created stream buffers. </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> <tt>removeSpoolDirectoryWhenStopping</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> <tt>true</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> Whether to remove the spool directory when stopping <a shape="rect" href="camelcontext.html" title="CamelContext">CamelContext</a>. </td></tr><tr><td colspan="1" rowspan="1" class="c
 onfluenceTd"> <tt>statisticsEnabled</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> <tt>false</tt> </td><td colspan="1" rowspan="1" class="confluenceTd"> Whether utilization statistics is enabled. By enabling this you can see these statics for example with JMX. </td></tr></tbody></table>
 </div>
 
 
@@ -344,6 +344,71 @@ context.setStreamCaching(true);
 </div></div>
 
 
+<h4><a shape="rect" name="Streamcaching-UsingspoolHeapMemoryWatermarkThreshold"></a>Using spoolHeapMemoryWatermarkThreshold</h4>
+
+<p>By default stream caching will spool only big payloads (128kb or bigger) to disk. However you can also set the spoolHeapMemoryWatermarkThreshold option which is a percentage of used heap memory. This can be used to also spool to disk when running low on memory.</p>
+
+<p>For example with:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
+    &lt;streamCaching id="myCacheConfig" spoolDirectory="/tmp/cachedir" spoolHeapMemoryWatermarkThreshold="70"/&gt;
+]]></script>
+</div></div>
+
+<p>Then notice that as spoolThreshold is default enabled with 128kb, then we have both thresholds in use (spoolThreads and spoolHeapMemoryWatermarkThreshold). And in this example then we only spool to disk if payload is &gt; 128kb and that used heap memory is &gt; 70%. The reason is that we have the option <tt>anySpoolRules</tt> as default <tt>false</tt>. That means both rules must be <tt>true</tt> (eg AND). </p>
+
+<p>If we want to spool to disk if either of the rules (eg OR), then we can do:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
+    &lt;streamCaching id="myCacheConfig" spoolDirectory="/tmp/cachedir" spoolHeapMemoryWatermarkThreshold="70" anySpoolRules="true"/&gt;
+]]></script>
+</div></div>
+
+<p>If we only want to spool to disk if we run low on memory then we can set:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
+    &lt;streamCaching id="myCacheConfig" spoolDirectory="/tmp/cachedir" spoolThreshold="-1" spoolHeapMemoryWatermarkThreshold="70"/&gt;
+]]></script>
+</div></div>
+
+<p>... then we do not use the spoolThreshold rule, and only the heap memory based is in use.</p>
+
+<h4><a shape="rect" name="Streamcaching-UsingcustomSpoolRuleimplementations"></a>Using custom SpoolRule implementations</h4>
+
+<p>You can implement your custom rules to determine if the stream should be spooled to disk. This can be done by implementing the interface <tt>org.apache.camel.spi.StreamCachingStrategy.SpoolRule</tt> which has a single method:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
+        boolean shouldSpoolCache(long length);
+]]></script>
+</div></div>
+
+<p>The length is the length of the stream. </p>
+
+<p>To use the rule then add it to the <tt>StreamCachingStrategy</tt> as shown below:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
+    SpoolRule mySpoolRule = ...
+    context.getStreamCachingStrategy().addSpoolRule(mySpoolRule);
+]]></script>
+</div></div>
+
+<p>And from XML you need to define a &lt;bean&gt; with your custom rule</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
+&lt;bean id="mySpoolRule" class="com.foo.MySpoolRule"/&gt;
+
+&lt;streamCaching id="myCacheConfig" spoolDirectory="/tmp/cachedir" spoolRules="mySpoolRule"/&gt;
+]]></script>
+</div></div>
+
+<p>Using the <tt>spoolRules</tt> attribute on &lt;streamCaching&gt;. if you have more rules, then separate them by comma.</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
+&lt;streamCaching id="myCacheConfig" spoolDirectory="/tmp/cachedir" spoolRules="mySpoolRule,myOtherSpoolRule"/&gt;
+]]></script>
+</div></div>
+
+
 <h3><a shape="rect" name="Streamcaching-Howitworks%3F"></a>How it works?</h3>
 <p>In order to determine if a type requires caching, we leverage the <a shape="rect" href="type-converter.html" title="Type Converter">type converter </a> feature.  Any type that requires stream caching can be converted into an <b><tt>org.apache.camel.StreamCache</tt></b> instance.</p></div>
         </td>