Add a few words about the image cache and how to empty it.

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@196434 13f79535-47bb-0310-9956-ffa450edef68

2 files changed, 20 insertions, 0 deletions

diff --git a/src/documentation/content/xdocs/graphics.xml b/src/documentation/content/xdocs/graphics.xml
index d139e75d0..83739703f 100644
--- a/src/documentation/content/xdocs/graphics.xml
+++ b/src/documentation/content/xdocs/graphics.xml
@@ -237,5 +237,20 @@ into a raster graphic are not drawn properly in PDF. The image is opaque.
       <p>If you need a higher apparent output resolution for bitmapped images, first make sure that at least one dimension of the image is defined in your XSL-FO input. Apart from that, resolution problems are in the image file itself, and must be corrected there: use or create a higher-resolution image file.</p>
       <note>The explanation above describes only the basic default behavior. There are other attributes of the fo:external-graphic element that can affect the behavior described above.</note>
     </section>
+    <section id="caching">
+      <title>Image caching</title>
+      <p>
+        FOP caches images between runs. The URL is used as a key to identify images which means that when
+        a particular URL appears again, the image is taken from the cache. If you have a servlet that
+        generates a different image each time it is called with the same URL you need to use a constantly 
+        changing dummy parameter on the URL to avoid caching.
+      </p>
+      <p>
+        Currently, the images are not automatically released when an OutOfMemoryError is imminent. The
+        image cache can grow to a considerable size over time when a lot of different URLs are in use.
+        Starting with version 0.20.5 you can call <code>org.apache.fop.image.FopImageFactory.resetCache()</code>
+        to manually empty the cache. Image caching will be improved as part of our redesign effort.
+      </p>
+    </section>
   </body>
 </document>
diff --git a/src/documentation/content/xdocs/running.xml b/src/documentation/content/xdocs/running.xml
index 3105f4271..38416eb07 100644
--- a/src/documentation/content/xdocs/running.xml
+++ b/src/documentation/content/xdocs/running.xml
@@ -156,6 +156,11 @@ If you don't use table headers and footers, just start a new table every N rows.
 With headers and footers, consider integrating them as normal table rows, or, if they are used at page breaks, try to put the information into static content.
 You can then use markers to change them.
         </li>
+        <li>
+Clear the image cache. At the moment, images in the cache are not released automatically when an OutOfMemoryError is imminent.
+Starting with version 0.20.5 however, you can call <code>org.apache.fop.image.FopImageFactory.resetCache()</code> to empty the 
+<jump href="graphics.html#caching">image cache</jump>.
+        </li>
       </ul>
       <p>
 There are currently some bugs which cause FOP to go into a nonterminating loop, which will also often result in a memory overflow.