Adjust documentation to changes in outer API (FopFactory etc.).

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

6 files changed, 266 insertions, 193 deletions

diff --git a/src/documentation/content/xdocs/trunk/embedding.xml b/src/documentation/content/xdocs/trunk/embedding.xml
index 82ce4a065..db41a7998 100644
--- a/src/documentation/content/xdocs/trunk/embedding.xml
+++ b/src/documentation/content/xdocs/trunk/embedding.xml
@@ -32,15 +32,22 @@
       to embedded applications as well as command-line use, such as options and performance.
     </p>
     <p>
-      To embed Apache FOP in your application, instantiate org.apache.fop.apps.Fop.
-      You'll tell FOP in the constructor which output format (i.e. Renderer) to use.
-      Afterwards, you'll set the OutputStream to use to output the results of the
-      rendering (where applicable). You can customize FOP's behaviour by supplying
+      To embed Apache FOP in your application, instantiate a new org.apache.fop.apps.FopFactory
+      instance and create a new org.apache.fop.apps.Fop instance through one of the factory
+      methods of FopFactory. There, you can specify which output format (i.e. Renderer) to use 
+      and you can optionally set the OutputStream to use to output the results of the
+      rendering. You can customize FOP's behaviour by supplying
       your own FOUserAgent instance. The FOUserAgent can, for example, be used to
       set your own Renderer instance (details below). Finally, you retrieve a SAX 
       DefaultHandler instance from the Fop instance to which you can send your
       FO file.
     </p>
+    <note>
+      We recently changed FOP's outer API to what we consider the final API. This might require
+      some changes in your application. The main reasons for these changes were performance
+      improvements due to better reuse of reusable objects and reduced use of static variables
+      for added flexibility in complex environments.
+    </note>
   </section>
   <section id="basics">
     <title>Basic Usage Pattern</title>
@@ -52,32 +59,36 @@
     <p>Here is the basic pattern to render an XSL-FO file to PDF:
     </p>
     <source><![CDATA[
+import org.apache.fop.apps.FopFactory;
 import org.apache.fop.apps.Fop;
 import org.apache.fop.apps.MimeConstants;
 
 /*..*/
 
-// Step 1: Construct fop with desired output format
-Fop fop = new Fop(MimeConstants.MIME_PDF);
+// Step 1: Construct a FopFactory
+// (reuse if you plan to render multiple documents!)
+FopFactory fopFactory = FopFactory.newInstance();
 
 // Step 2: Setup output stream.
 // Note: Using BufferedOutputStream for performance reasons (helpful with FileOutputStreams).
 OutputStream out = new BufferedOutputStream(new FileOutputStream(new File("C:/Temp/myfile.pdf")));
+
 try {
-  fop.setOutputStream(out);
+  // Step 3: Construct fop with desired output format
+  Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF, out);
 
-  // Step 3: Setup JAXP using identity transformer
+  // Step 4: Setup JAXP using identity transformer
   TransformerFactory factory = TransformerFactory.newInstance();
   Transformer transformer = factory.newTransformer(); // identity transformer
            
-  // Step 4: Setup input and output for XSLT transformation 
+  // Step 5: Setup input and output for XSLT transformation 
   // Setup input stream
   Source src = new StreamSource(new File("C:/Temp/myfile.fo"));
 
   // Resulting SAX events (the generated FO) must be piped through to FOP
   Result res = new SAXResult(fop.getDefaultHandler());
             
-  // Step 5: Start XSLT transformation and FOP processing
+  // Step 6: Start XSLT transformation and FOP processing
   transformer.transform(src, res);
 
 } finally {
@@ -89,16 +100,24 @@ try {
     </p>
     <ul>
       <li>
-        <strong>Step 1:</strong> You create a new Fop instance and set it up for PDF 
-        output.
+        <strong>Step 1:</strong> You create a new FopFactory instance. The FopFactory holds 
+        references to configuration information and cached data. It's important to reuse this
+        instance if you plan to render multiple documents during a JVM's lifetime.
+      </li>
+      <li>
+        <strong>Step 2:</strong> You set up an OutputStream that the generated document
+        will be written to. It's a good idea to buffer the OutputStream as demonstrated 
+        to improve performance.
       </li>
       <li>
-        <strong>Step 2:</strong> You tell FOP where to save the generated PDF file 
-        later. It's a good idea to buffer the OutputStream as demonstrated to improve 
-        performance.
+        <strong>Step 3:</strong> You create a new Fop instance through one of the factory
+        methods on the FopFactory. You tell the FopFactory what your desired output format
+        is. This is done by using the MIME type of the desired output format (ex. "application/pdf").
+        You can use one of the MimeConstants.* constants. The second parameter is the
+        OutputStream you've setup up in step 2.
       </li>
       <li>
-        <strong>Step 3:</strong> We recommend that you use JAXP Transformers even 
+        <strong>Step 4</strong> We recommend that you use JAXP Transformers even 
         if you don't do XSLT transformations to generate the XSL-FO file. This way 
         you can always use the same basic pattern. The example here sets up an 
         "identity transformer" which just passes the input (Source) unchanged to the 
@@ -106,7 +125,7 @@ try {
         XSLT transformations.
       </li>
       <li>
-        <strong>Step 4:</strong> Here you set up the input and output for the XSLT 
+        <strong>Step 5:</strong> Here you set up the input and output for the XSLT 
         transformation. The Source object is set up to load the "myfile.fo" file. 
         The Result is set up so the output of the XSLT transformation is sent to FOP. 
         The FO file is sent to FOP in the form of SAX events which is the most efficient 
@@ -114,7 +133,7 @@ try {
         because that affects performance negatively.
       </li>
       <li>
-        <strong>Step 5:</strong> Finally, we start the XSLT transformation by starting 
+        <strong>Step 6:</strong> Finally, we start the XSLT transformation by starting 
         the JAXP Transformer. As soon as the JAXP Transformer starts to send its output 
         to FOP, FOP itself starts its processing in the background. When the 
         <code>transform()</code> method returns FOP will also have finished converting 
@@ -141,11 +160,6 @@ try {
       to a file to check if that part generates the expected output. An example for that
       can be found in the <a href="#examples">Embedding examples</a> (See "ExampleXML2FO").
     </p>
-    <note>
-      Please be aware that you should not reuse a Fop instance for additional rendering runs.
-      Recreate a new instance for each rendering run. This is a relatively inexpensive 
-      operation and will be further optimized shortly.
-    </note>
     <section id="basic-logging">
       <title>Logging</title>
       <p>
@@ -187,7 +201,7 @@ try {
         document you'd like to render. FOP processing starts as soon as the DefaultHandler's
         <code>startDocument()</code> methods is called. Processing stops again when the
         DefaultHandler's <code>endDocument()</code> method is called. Please refer to the basic
-        usage pattern shown above to render a simply XSL-FO document.
+        usage pattern shown above to render a simple XSL-FO document.
       </p>
     </section>
 
@@ -255,140 +269,174 @@ try {
   <section id="config-internal">
     <title>Configuring Apache FOP Programmatically</title>
     <p>
-      Apache FOP provides a class called FOUserAgent which is used to customize FOP's
-      behaviour. If you wish to do that, the first step is to create your own instance
-      of FOUserAgent and pass that to the Fop constructor:
+      Apache FOP provides two levels on which you can customize FOP's
+      behaviour: the FopFactory and the user agent.
     </p>
-    <source><![CDATA[
-FOUserAgent userAgent = new FOUserAgent();
-Fop fop = new Fop(MimeConstants.MIME_POSTSCRIPT, userAgent);]]></source>
-    <p>
-      You can do all sorts of things on the user agent:
-    </p>
-    <ul>
-      <li>
-        <p>
-          The <strong>base URL</strong> to use when resolving relative URLs. Example:
-        </p>
-        <source>userAgent.setBaseURL("file:///C:/Temp/");</source>
-      </li>
-      <li>
-        <p>
-          The <strong>font base URL</strong> to use when resolving relative URLs for fonts. Example:
-        </p>
-        <source>userAgent.setFontBaseURL("file:///C:/Temp/fonts");</source>
-      </li>
-      <li>
-        <p>
-          Disable <strong>strict validation</strong>. When disabled FOP is less strict about the rules established by the XSL-FO specification. Example:
-        </p>
-        <source>userAgent.setStrictValidation(false);</source>
-      </li>
-      <li>
-        <p>
-          Set the <strong>producer</strong> of the document. This is metadata information that can be used for certain output formats such as PDF. The default producer is "Apache FOP". Example:
-        </p>
-        <source>userAgent.setProducer("MyKillerApplication");</source>
-      </li>
-      <li>
-        <p>
-          Set the <strong>creating user</strong> of the document. This is metadata information that can be used for certain output formats such as PDF. Example:
-        </p>
-        <source>userAgent.setCreator("John Doe");</source>
-      </li>
-      <li>
-        <p>
-          Set the <strong>author</strong> of the document. This is metadata information that can be used for certain output formats such as PDF. Example:
-        </p>
-        <source>userAgent.setAuthor("John Doe");</source>
-      </li>
-      <li>
-        <p>
-          Override the <strong>creation date and time</strong> of the document. This is metadata information that can be used for certain output formats such as PDF. Example:
-        </p>
-        <source>userAgent.setCreationDate(new Date());</source>
-      </li>
-      <li>
-        <p>
-          Set the <strong>title</strong> of the document. This is metadata information that can be used for certain output formats such as PDF. Example:
-        </p>
-        <source>userAgent.setTitle("Invoice No 138716847");</source>
-      </li>
-      <li>
-        <p>
-          Set the <strong>keywords</strong> of the document. This is metadata information that can be used for certain output formats such as PDF. Example:
-        </p>
-        <source>userAgent.setKeywords("XML XSL-FO");</source>
-      </li>
-      <li>
-        <p>
-          Set the <strong>source resolution</strong> for the document. This is used internally to determine the pixel 
-          size for SVG images and bitmap images without resolution information. Default: 72 dpi. Example:
-        </p>
-        <source>userAgent.setSourceResolution(96); //=96dpi (dots/pixels per Inch)</source>
-      </li>
-      <li>
-        <p>
-          Set the <strong>target resolution</strong> for the document. This is used to 
-          specify the output resolution for bitmap images generated by bitmap renderers 
-          (such as the TIFF renderer) and by bitmaps generated by Apache Batik for filter 
-          effects and such. Default: 72 dpi. Example:
-        </p>
-        <source>userAgent.setTargetResolution(300); //=300dpi (dots/pixels per Inch)</source>
-      </li>
-      <li>
-        <p>
-          Set <strong>your own Renderer instance</strong>. If you want to supply your own renderer or 
-          configure a Renderer in a special way you can give the instance to the FOUserAgent. Normally,
-          the Renderer instance is created by FOP. Example:
-        </p>
-        <source>userAgent.setRendererOverride(myRenderer); //myRenderer is an org.apache.fop.render.Renderer</source>
-      </li>
-      <li>
-        <p>
-          Set <strong>your own FOEventHandler instance</strong>. If you want to supply your own FOEventHandler or 
-          configure an FOEventHandler subclass in a special way you can give the instance to the FOUserAgent. Normally, 
-          the FOEventHandler instance is created by FOP. Example:
-        </p>
-        <source>userAgent.setFOEventHandlerOverride(myFOEventHandler); //myFOEventHandler is an org.apache.fop.fo.FOEventHandler</source>
-      </li>
-      <li>
-        <p>
-          Manually add a <strong>ElementMapping instance</strong>. If you want to supply a special FOP extension
-          you can give the instance to the FOUserAgent. Normally, the FOP extensions can be automatically detected 
-          (see the documentation on extension for more info).
-        </p>
-        <source>userAgent.addElementMapping(myElementMapping); //myElementMapping is a org.apache.fop.fo.ElementMapping</source>
-      </li>
-      <li>
-        <p>
-          Set a <strong>URIResolver</strong> for custom URI resolution. By supplying a JAXP URIResolver you can add
-          custom URI resolution functionality to FOP. For example, you can use 
-          <a href="ext:xml.apache.org/commons/resolver">Apache XML Commons Resolver</a> to make use of XCatalogs.
-        </p>
-        <source>userAgent.setURIResolver(myResolver); //myResolver is a javax.xml.transform.URIResolver</source>
-      </li>
-      <li>
-        <p>
-          Set the <strong>parameters for PDF encryption</strong> for the document. If you create PDF files you can 
-          instantiate and set an org.apache.fop.pdf.PDFEncryptionParams object. Example:
-        </p>
-        <source>userAgent.setPDFEncryptionParams(new PDFEncryptionParams(null, "owner", false, false, true, true));</source>
-      </li>
-      <li>
-        <p>
-          Enable an <strong>alternative set of rules for text indents</strong> that tries to mimic the behaviour of many commercial 
-          FO implementations that chose to break the specification in this aspect. The default of this option is 
-          'false' which causes Apache FOP to behave exactly as describes in the specification. To enable the 
-          alternative behaviour, call:
-        </p>
-        <source>userAgent.setBreakIndentInheritanceOnReferenceAreaBoundary(true);</source>
-      </li>
-    </ul>
-    <note>
-      You should not reuse an FOUserAgent instance between FOP rendering runs although you can. Especially
-      in multi-threaded environment, this is a bad idea.
-    </note>
+    <section id="fop-factory">
+      <title>Customizing the FopFactory</title>
+      <p>
+        The FopFactory holds configuration data and references to objects which are reusable over
+        multiple rendering runs. It's important to instantiate it only once (except in special 
+        environments) and reuse it every time to create new FOUserAgent and Fop instances.
+      </p>
+      <p>
+        You can set all sorts of things on the FopFactory:
+      </p>
+      <ul>
+        <li>
+          <p>
+            The <strong>font base URL</strong> to use when resolving relative URLs for fonts. Example:
+          </p>
+          <source>fopFactory.setFontBaseURL("file:///C:/Temp/fonts");</source>
+        </li>
+        <li>
+          <p>
+            Disable <strong>strict validation</strong>. When disabled FOP is less strict about the rules 
+            established by the XSL-FO specification. Example:
+          </p>
+          <source>fopFactory.setStrictValidation(false);</source>
+        </li>
+        <li>
+          <p>
+            Enable an <strong>alternative set of rules for text indents</strong> that tries to mimic the behaviour of many commercial 
+            FO implementations that chose to break the specification in this aspect. The default of this option is 
+            'false' which causes Apache FOP to behave exactly as describes in the specification. To enable the 
+            alternative behaviour, call:
+          </p>
+          <source>fopFactory.setBreakIndentInheritanceOnReferenceAreaBoundary(true);</source>
+        </li>
+        <li>
+          <p>
+            Set the <strong>source resolution</strong> for the document. This is used internally to determine the pixel 
+            size for SVG images and bitmap images without resolution information. Default: 72 dpi. Example:
+          </p>
+          <source>fopFactory.setSourceResolution(96); //=96dpi (dots/pixels per Inch)</source>
+        </li>
+        <li>
+          <p>
+            Manually add a <strong>ElementMapping instance</strong>. If you want to supply a special FOP extension
+            you can give the instance to the FOUserAgent. Normally, the FOP extensions can be automatically detected 
+            (see the documentation on extension for more info).
+          </p>
+          <source>fopFactory.addElementMapping(myElementMapping); //myElementMapping is a org.apache.fop.fo.ElementMapping</source>
+        </li>
+        <li>
+          <p>
+            Set a <strong>URIResolver</strong> for custom URI resolution. By supplying a JAXP URIResolver you can add
+            custom URI resolution functionality to FOP. For example, you can use 
+            <a href="ext:xml.apache.org/commons/resolver">Apache XML Commons Resolver</a> to make use of XCatalogs.
+          </p>
+          <source>fopFactory.setURIResolver(myResolver); //myResolver is a javax.xml.transform.URIResolver</source>
+          <note>
+            Both the FopFactory and the FOUserAgent have a method to set a URIResolver. The URIResolver on the FopFactory
+            is primarily used to resolve URIs on factory-level (hyphenation patterns, for example) and it is always used 
+            if no other URIResolver (for example on the FOUserAgent) resolved the URI first.
+          </note>
+        </li>
+      </ul>
+    </section>
+    <section id="user-agent">
+      <title>Customizing the User Agent</title>
+      <p>
+        The user agent is the entity that allows you to interact with a single rendering run, i.e. the processing of a single 
+        document. If you wish to customize the user agent's behaviour, the first step is to create your own instance
+        of FOUserAgent using the respective factory method on FopFactory and pass that 
+        to the factory method that will create a new Fop instance:
+      </p>
+      <source><![CDATA[
+  FopFactory fopFactory = FopFactory.newInstance(); //Reuse the FopFactory if possible!
+  FOUserAgent userAgent = fopFactory.newFOUserAgent();
+  Fop fop = fopFactory.newFop(MimeConstants.MIME_POSTSCRIPT, userAgent);]]></source>
+      <p>
+        You can do all sorts of things on the user agent:
+      </p>
+      <ul>
+        <li>
+          <p>
+            The <strong>base URL</strong> to use when resolving relative URLs. Example:
+          </p>
+          <source>userAgent.setBaseURL("file:///C:/Temp/");</source>
+        </li>
+        <li>
+          <p>
+            Set the <strong>producer</strong> of the document. This is metadata information that can be used for certain output formats such as PDF. The default producer is "Apache FOP". Example:
+          </p>
+          <source>userAgent.setProducer("MyKillerApplication");</source>
+        </li>
+        <li>
+          <p>
+            Set the <strong>creating user</strong> of the document. This is metadata information that can be used for certain output formats such as PDF. Example:
+          </p>
+          <source>userAgent.setCreator("John Doe");</source>
+        </li>
+        <li>
+          <p>
+            Set the <strong>author</strong> of the document. This is metadata information that can be used for certain output formats such as PDF. Example:
+          </p>
+          <source>userAgent.setAuthor("John Doe");</source>
+        </li>
+        <li>
+          <p>
+            Override the <strong>creation date and time</strong> of the document. This is metadata information that can be used for certain output formats such as PDF. Example:
+          </p>
+          <source>userAgent.setCreationDate(new Date());</source>
+        </li>
+        <li>
+          <p>
+            Set the <strong>title</strong> of the document. This is metadata information that can be used for certain output formats such as PDF. Example:
+          </p>
+          <source>userAgent.setTitle("Invoice No 138716847");</source>
+        </li>
+        <li>
+          <p>
+            Set the <strong>keywords</strong> of the document. This is metadata information that can be used for certain output formats such as PDF. Example:
+          </p>
+          <source>userAgent.setKeywords("XML XSL-FO");</source>
+        </li>
+        <li>
+          <p>
+            Set the <strong>target resolution</strong> for the document. This is used to 
+            specify the output resolution for bitmap images generated by bitmap renderers 
+            (such as the TIFF renderer) and by bitmaps generated by Apache Batik for filter 
+            effects and such. Default: 72 dpi. Example:
+          </p>
+          <source>userAgent.setTargetResolution(300); //=300dpi (dots/pixels per Inch)</source>
+        </li>
+        <li>
+          <p>
+            Set <strong>your own Renderer instance</strong>. If you want to supply your own renderer or 
+            configure a Renderer in a special way you can give the instance to the FOUserAgent. Normally,
+            the Renderer instance is created by FOP. Example:
+          </p>
+          <source>userAgent.setRendererOverride(myRenderer); //myRenderer is an org.apache.fop.render.Renderer</source>
+        </li>
+        <li>
+          <p>
+            Set <strong>your own FOEventHandler instance</strong>. If you want to supply your own FOEventHandler or 
+            configure an FOEventHandler subclass in a special way you can give the instance to the FOUserAgent. Normally, 
+            the FOEventHandler instance is created by FOP. Example:
+          </p>
+          <source>userAgent.setFOEventHandlerOverride(myFOEventHandler); //myFOEventHandler is an org.apache.fop.fo.FOEventHandler</source>
+        </li>
+        <li>
+          <p>
+            Set a <strong>URIResolver</strong> for custom URI resolution. By supplying a JAXP URIResolver you can add
+            custom URI resolution functionality to FOP. For example, you can use 
+            <a href="ext:xml.apache.org/commons/resolver">Apache XML Commons Resolver</a> to make use of XCatalogs.
+          </p>
+          <source>userAgent.setURIResolver(myResolver); //myResolver is a javax.xml.transform.URIResolver</source>
+          <note>
+            Both the FopFactory and the FOUserAgent have a method to set a URIResolver. The URIResolver on the FOUserAgent is
+            used for resolving URIs which are document-related. If it's not set or cannot resolve a URI, the URIResolver
+            from the FopFactory is used.
+          </note>
+        </li>
+      </ul>
+      <note>
+        You should not reuse an FOUserAgent instance between FOP rendering runs although you can. Especially
+        in multi-threaded environment, this is a bad idea.
+      </note>
+    </section>
   </section>
   <section id="config-external">
     <title>Using a Configuration File</title>
@@ -404,7 +452,11 @@ import org.apache.avalon.framework.configuration.DefaultConfigurationBuilder;
 
 DefaultConfigurationBuilder cfgBuilder = new DefaultConfigurationBuilder();
 Configuration cfg = cfgBuilder.buildFromFile(new File("C:/Temp/mycfg.xml"));
-userAgent.setUserConfig(cfg);]]></source>
+fopFactory.setUserConfig(cfg);
+
+/* ..or.. */
+
+fopFactory.setUserConfig(new File("C:/Temp/mycfg.xml"));]]></source>
     <p>
       The layout of the configuration file is described on the <a href="configuration.html">Configuration page</a>.
     </p>
@@ -414,11 +466,10 @@ userAgent.setUserConfig(cfg);]]></source>
     <section id="object-reuse">
       <title>Object reuse</title>
       <p>
-        At the moment, the Fop instances shouldn't be reused. Please recreate
-        Fop and FOUserAgent instances for each rendering run until further notice.
-        We will likely add an additional object which will carry information
-        and configuration which can be reused between rendering runs to further
-        optimize this.
+        Fop instances shouldn't (and can't) be reused. Please recreate
+        Fop and FOUserAgent instances for each rendering run using the FopFactory.
+        This is a cheap operation as all reusable information is held in the 
+        FopFactory. That's why it's so important to reuse the FopFactory instance.
      </p>
     </section>
     <section id="awt">
@@ -481,14 +532,18 @@ userAgent.setUserConfig(cfg);]]></source>
         Use an XSLT compiler like <a class="fork" href="http://xml.apache.org/xalan-j/xsltc_usage.html">XSLTC</a>
         that comes with Xalan-J.
       </li>
+      <li>
+        Fine-tune your stylesheet to make the XSLT process more efficient and to create XSL-FO that can
+        be processed by FOP more efficiently. Less is more: Try to make use of property inheritance where possible.
+      </li>
     </ul>
   </section>
   <section id="multithreading">
     <title>Multithreading FOP</title>
     <p>
       Apache FOP may currently not be completely thread safe.
-      FOP uses some static variables (for example for the image cache). This code 
-      has not been fully tested for multi-threading issues, yet.
+      The code has not been fully tested for multi-threading issues, yet.
+      If you encounter any suspicious behaviour, please notify us.
     </p>
     <p>
       There is also a known issue with fonts being jumbled between threads when using 
diff --git a/src/documentation/content/xdocs/trunk/intermediate.xml b/src/documentation/content/xdocs/trunk/intermediate.xml
index 360766241..ad42f2645 100644
--- a/src/documentation/content/xdocs/trunk/intermediate.xml
+++ b/src/documentation/content/xdocs/trunk/intermediate.xml
@@ -69,13 +69,15 @@
         The basic pattern to parse the IF format looks like this:
       </p>
       <source><![CDATA[
+FopFactory fopFactory = FopFactory.newInstance();      
+      
 // Setup output
 OutputStream out = new java.io.FileOutputStream(pdffile);
 out = new java.io.BufferedOutputStream(out);
 try {
     //Setup fonts and user agent
     FontInfo fontInfo = new FontInfo();
-    FOUserAgent userAgent = new FOUserAgent();
+    FOUserAgent userAgent = fopFactory.newFOUserAgent();
 
     //Construct the AreaTreeModel that will received the individual pages
     AreaTreeModel treeModel = new RenderPagesModel(userAgent, 
diff --git a/src/documentation/content/xdocs/trunk/output.xml b/src/documentation/content/xdocs/trunk/output.xml
index 8402a9075..8880aca21 100644
--- a/src/documentation/content/xdocs/trunk/output.xml
+++ b/src/documentation/content/xdocs/trunk/output.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" standalone="no"?>
 <!--
-  Copyright 1999-2005 The Apache Software Foundation
+  Copyright 1999-2006 The Apache Software Foundation
 
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
@@ -125,8 +125,8 @@ out = proc.getOutputStream();]]></source>
   try {
     ByteArrayOutputStream fopout = new ByteArrayOutputStream();
     FileOutputStream outfile = new FileOutputStream(args[2]);
-    Fop fop = new Fop(MimeConstants.MIME_PDF);
-    fop.setOutputStream(fopout);
+    FopFactory fopFactory = FopFactory.newInstance();
+    Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF, fopout);
     
     Transformer transformer = TransformerFactory.newInstance().newTransformer(
         new StreamSource(new File(args[1])));
diff --git a/src/documentation/content/xdocs/trunk/pdfencryption.xml b/src/documentation/content/xdocs/trunk/pdfencryption.xml
index 2c7742d8d..aca98135a 100755
--- a/src/documentation/content/xdocs/trunk/pdfencryption.xml
+++ b/src/documentation/content/xdocs/trunk/pdfencryption.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" standalone="no"?>
 <!--
-  Copyright 1999-2005 The Apache Software Foundation
+  Copyright 1999-2006 The Apache Software Foundation
 
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
@@ -139,11 +139,11 @@ import org.apache.fop.pdf.PDFEncryptionParams;
 
 [..]
 
-FOUserAgent userAgent = new FOUserAgent();
-useragent.setPDFEncryptionParams(new PDFEncryptionParams(
+FOUserAgent userAgent = fopFactory.newFOUserAgent();
+useragent.getRendererOptions().put("encryption-params", new PDFEncryptionParams(
     null, "password", false, false, true, true));
-Fop fop = new Fop(MimeConstants.MIME_PDF, userAgent);
-driver.setOutputStream(...]]></source>
+Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF, userAgent);
+[..]]]></source>
       <p>
         The parameters for the constructor of PDFEncryptionParams are:
       </p>
@@ -155,6 +155,18 @@ driver.setOutputStream(...]]></source>
         <li>allowEditContent: true if editing content is allowed</li>
         <li>allowEditAnnotations: true if editing annotations is allowed</li>
       </ol>
+      <p>
+        Alternatively, you can set each value separately in the Map provided by 
+        FOUserAgent.getRendererOptions() by using the following keys:
+      </p>
+      <ol>
+        <li>user-password: String</li>
+        <li>owner-password: String</li>
+        <li>noprint: Boolean or "true"/"false"</li>
+        <li>nocopy: Boolean or "true"/"false"</li>
+        <li>noedit: Boolean or "true"/"false"</li>
+        <li>noannotations: Boolean or "true"/"false"</li>
+      </ol>
     </section>
     <section>
       <title>Environment</title>
diff --git a/src/documentation/content/xdocs/trunk/servlets.xml b/src/documentation/content/xdocs/trunk/servlets.xml
index 86681ccc9..b26cef592 100644
--- a/src/documentation/content/xdocs/trunk/servlets.xml
+++ b/src/documentation/content/xdocs/trunk/servlets.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" standalone="no"?>
 <!--
-  Copyright 1999-2005 The Apache Software Foundation
+  Copyright 1999-2006 The Apache Software Foundation
 
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
@@ -46,6 +46,11 @@
       </ul>
       <p/>
       <p>The source code for the servlet can be found under {fop-dir}/src/java/org/apache/fop/servlet/FopServlet.java.</p>
+      <note>
+        This example servlet should not be used on a public web server connected to the Internet as it does not contain
+        any measures to prevent Denial-of-Service-Attacks. It is provided as an example and as a starting point for
+        your own servlet.
+      </note>
     </section>
     <section id="servlet">
       <title>Create your own Servlet</title>
@@ -57,14 +62,15 @@
         <p>
           Here is a minimal code snippet to demonstrate the basics:
         </p>
-        <source>public void doGet(HttpServletRequest request,
+        <source>private FopFactory fopFactory = FopFactory.newInstance();
+private TransformerFactory tFactory = TransformerFactory.newInstance();
+        
+public void doGet(HttpServletRequest request,
                    HttpServletResponse response) throws ServletException {
     try {
         response.setContentType("application/pdf");
-        Fop fop = new Fop(MimeConstants.MIME_PDF);
-        fop.setOutputStream(response.getOutputStream());
-        TransformerFactory factory = TransformerFactory.newInstance();
-        Transformer transformer = factory.newTransformer();
+        Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF, response.getOutputStream());
+        Transformer transformer = tFactory.newTransformer();
         Source src = new StreamSource("foo.fo");
         Result res = new SAXResult(fop.getDefaultHandler());
         transformer.transform(src, res);
@@ -81,30 +87,29 @@
       <section id="xslt">
         <title>Adding XSL tranformation (XSLT)</title>
         <p>
-          A common requirement is the to transform an XML source to
+          A common requirement is to transform an XML source to
           XSL-FO using an XSL transformation. It is recommended to use
           JAXP for this task. The following snippet shows the basic
           code:
         </p>
-        <source>
-protected TransformerFactory transformerFactory;
+        <source>private FopFactory fopFactory = FopFactory.newInstance();
+private TransformerFactory tFactory = TransformerFactory.newInstance();
 
 public void init() throws ServletException {
-    this.transformerFactory = TransformerFactory.newInstance();
+    //Optionally customize the FopFactory and TransformerFactory here
 }
 
 [..]
 
-    //Setup FOP
-    Fop fop = new Fop(MimeConstants.MIME_PDF);
-
     //Setup a buffer to obtain the content length
     ByteArrayOutputStream out = new ByteArrayOutputStream();
-    fop.setOutputStream(out);
+
+    //Setup FOP
+    Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF, out);
 
     //Setup Transformer
     Source xsltSrc = new StreamSource(new File("foo-xml2fo.xsl"));
-    Transformer transformer = this.transformerFactory.newTransformer(xsltSrc);
+    Transformer transformer = tFactory.newTransformer(xsltSrc);
 
     //Make sure the XSL transformation's result is piped through to FOP
     Result res = new SAXResult(fop.getDefaultHandler());
@@ -138,7 +143,7 @@ public void init() throws ServletException {
         </p>
         <p>
           Because you have an explicit <code>Transformer</code> object, you can also use it to 
-          explicitly set parameters for the transformation run.
+          explicitely set parameters for the transformation run.
         </p>
       </section>
       <section id="cfg">
@@ -251,5 +256,4 @@ public void init() throws ServletException {
       </p>
     </section>
   </body>
-</document>
-<!-- Last Line of $RCSfile$ -->
+</document>
\ No newline at end of file
diff --git a/src/documentation/skinconf.xml b/src/documentation/skinconf.xml
index b1128d267..1083dd438 100644
--- a/src/documentation/skinconf.xml
+++ b/src/documentation/skinconf.xml
@@ -90,7 +90,7 @@ which will be used to configure the chosen Forrest skin.
   <favicon-url></favicon-url>
 
   <!-- The following used to construct a copyright statement -->
-  <year>1999-2005</year>
+  <year>1999-2006</year>
   <vendor>The Apache Software Foundation.</vendor>
   <!-- The optional copyright-link URL will be used as a link in the
     copyright statement