New feature: "Intermediate format" (IF). The IF is basically the XML dialect written by the area tree renderer (XMLRenderer). A new parser for this format allows reparsing a serialized and possibly modified area tree and rendering it to the final target format. More details on the Wiki at http://wiki.apache.org/xmlgraphics-fop/AreaTreeIntermediateXml. No advanced features have been implemented, yet, only the basic functionality. The whole change should be fully backwards-compatible WRT the outer FOP API except maybe for FOTreeBuilder.addElementMapping(), and the area tree XML which got small changes.

The area tree has been cleaned up. The serializability has been restored. The CachedRenderPagesModel works again and can, in certain situations, decrease the maximum amount of memory held at one point in time. Some adjustments were necessary in the area tree to help the work of the AreaTreeParser.

The AreaTreeParser is new and is responsible for parsing area tree XML files and adding pages to a RenderPagesModel instance. It is SAX-based and should be pretty efficient.

XMLUnit (http://xmlunit.sourceforge.net, BSD license) is a new dependency for the test code. It is used to verify the correctness of the intermediate format code. It doesn't have to be installed for the build to run through, though.

ElementMapping got a new method getDOMImplementation() which provides the DOMImplementation used to handle a subdocument of a particular namespace. For example, SVG uses Batik's SVG DOM. The AreaTreeParser needs that to properly recreate foreign objects because it can't use the mechanism of the FO tree. The default implementation returns null.

The ElementMapping instances are no longer maintained by the FOTreeBuilder, but by the newly created ElementMappingRegistry class. It is expected that the instance of this class is moved from the FOTreeBuilder and the AreaTreeParser's Handler class to the "environment class" once it is created to cut down on the startup time for each processed document.

The XMLRenderer has been slightly modified to improve the serialization/deserialization qualities of the area tree XML format.

The XMLRenderer can now mimic another renderer (see mimicRenderer(Renderer)) in order to use its font setup. That way it is made certain that the reparsed area tree will render to the final target format exactly as expected.

Fixed a bug in the XMLHandlerRegistry which did not always return the right XMLHandler for every situation.

Added a DefaultErrorListener to the util package. I've had problems with Xalan-J swallowing exceptions with its default ErrorListener, so I added a simple one for convenience and use in AreaTreeParser.

Example code for working with the AreaTreeParser can be found in examples/embedding. Documentation will follow.

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

3 files changed, 232 insertions, 4 deletions

diff --git a/examples/embedding/java/embedding/intermediate/ExampleConcat.java b/examples/embedding/java/embedding/intermediate/ExampleConcat.java
new file mode 100644
index 000000000..845d3bfbf
--- /dev/null
+++ b/examples/embedding/java/embedding/intermediate/ExampleConcat.java
@@ -0,0 +1,214 @@
+/*
+ * Copyright 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.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/* $Id: ExampleDOM2PDF.java 332791 2005-11-12 15:58:07Z jeremias $ */
+ 
+package embedding.intermediate;
+
+import java.io.File;
+import java.io.IOException;
+import java.io.OutputStream;
+
+import javax.xml.transform.Result;
+import javax.xml.transform.Source;
+import javax.xml.transform.Transformer;
+import javax.xml.transform.TransformerException;
+import javax.xml.transform.TransformerFactory;
+import javax.xml.transform.sax.SAXResult;
+import javax.xml.transform.stream.StreamSource;
+
+import org.apache.fop.apps.FOPException;
+import org.apache.fop.apps.FOUserAgent;
+import org.apache.fop.apps.Fop;
+import org.apache.fop.apps.MimeConstants;
+import org.apache.fop.area.AreaTreeModel;
+import org.apache.fop.area.AreaTreeParser;
+import org.apache.fop.area.RenderPagesModel;
+import org.apache.fop.fonts.FontInfo;
+import org.apache.fop.render.Renderer;
+import org.apache.fop.render.xml.XMLRenderer;
+import org.xml.sax.SAXException;
+
+import embedding.ExampleObj2XML;
+import embedding.model.ProjectMember;
+import embedding.model.ProjectTeam;
+
+/**
+ * Example for the intermediate format that demonstrates the concatenation of two documents
+ * renderered to the intermediate format. A single PDF file is generated from the two intermediate
+ * files.
+ */
+public class ExampleConcat {
+
+    /**
+     * Creates a sample ProjectTeam instance for this demo.
+     * @return ProjectTeam the newly created ProjectTeam instance
+     */
+    public static ProjectTeam createAnotherProjectTeam() {
+        ProjectTeam team = new ProjectTeam();
+        team.setProjectName("The Dynamic Duo");
+        team.addMember(new ProjectMember(
+                "Batman", "lead", "batman@heroes.org"));
+        team.addMember(new ProjectMember(
+                "Robin", "aid", "robin@heroes.org"));
+        return team;
+    }
+
+    /**
+     * Converts an XSL-FO document to an intermediate file.
+     * @param src the source file
+     * @param xslt the stylesheet file
+     * @param intermediate the target intermediate file (area tree XML)
+     * @throws IOException In case of an I/O problem
+     * @throws FOPException In case of a FOP problem
+     * @throws TransformerException In case of a XSL transformation problem
+     */
+    public void convertToIntermediate(Source src, Source xslt, File intermediate) 
+                throws IOException, FOPException, TransformerException {
+        
+        //Create a user agent
+        FOUserAgent userAgent = new FOUserAgent();
+        
+        //Create an instance of the target renderer so the XMLRenderer can use its font setup
+        Renderer targetRenderer = userAgent.getRendererFactory().createRenderer(
+                userAgent, MimeConstants.MIME_PDF); 
+        
+        //Create the XMLRenderer to create the intermediate format (area tree XML)
+        XMLRenderer xmlRenderer = new XMLRenderer();
+        xmlRenderer.setUserAgent(userAgent);
+        
+        //Tell the XMLRenderer to mimic the target renderer
+        xmlRenderer.mimicRenderer(targetRenderer);
+        
+        //Make sure the prepared XMLRenderer is used
+        userAgent.setRendererOverride(xmlRenderer);
+        
+        // Construct fop (the MIME type here is unimportant due to the override on the user agent)
+        Fop fop = new Fop(MimeConstants.MIME_FOP_AREA_TREE, userAgent);
+
+        // Setup output
+        OutputStream out = new java.io.FileOutputStream(intermediate);
+        out = new java.io.BufferedOutputStream(out);
+        try {
+            fop.setOutputStream(out);
+
+            // Setup XSLT
+            TransformerFactory factory = TransformerFactory.newInstance();
+            Transformer transformer;
+            if (xslt != null) {
+                transformer = factory.newTransformer(xslt);
+            } else {
+                transformer = factory.newTransformer();
+            }
+        
+            // Resulting SAX events (the generated FO) must be piped through to FOP
+            Result res = new SAXResult(fop.getDefaultHandler());
+
+            // Start XSLT transformation and FOP processing
+            transformer.transform(src, res);
+        } finally {
+            out.close();
+        }
+    }
+
+    /**
+     * Concatenates an array of intermediate files to a single PDF file.
+     * @param files the array of intermediate files (area tree XML)
+     * @param pdffile the target PDF file
+     * @throws IOException In case of an I/O problem
+     * @throws TransformerException In case of a XSL transformation problem
+     * @throws SAXException In case of an XML-related problem
+     */
+    public void concatToPDF(File[] files, File pdffile) 
+            throws IOException, TransformerException, SAXException {
+        // 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();
+
+            //Construct the AreaTreeModel that will received the individual pages
+            AreaTreeModel treeModel = new RenderPagesModel(userAgent, 
+                    MimeConstants.MIME_PDF, fontInfo, out);
+            
+            //Iterate over all intermediate files
+            AreaTreeParser parser = new AreaTreeParser();
+            for (int i = 0; i < files.length; i++) {
+                Source src = new StreamSource(files[i]);
+                parser.parse(src, treeModel, userAgent);
+            }
+            
+            //Signal the end of the processing. The renderer can finalize the target document.
+            treeModel.endDocument();
+        } finally {
+            out.close();
+        }
+    }
+    
+    /**
+     * Main method.
+     * @param args command-line arguments
+     */
+    public static void main(String[] args) {
+        try {
+            System.out.println("FOP ExampleConcat\n");
+            
+            //Setup directories
+            File baseDir = new File(".");
+            File outDir = new File(baseDir, "out");
+            outDir.mkdirs();
+            
+            //Setup output file
+            File xsltfile = new File(baseDir, "xml/xslt/projectteam2fo.xsl");
+            File[] files = new File[] {
+                    new File(outDir, "team1.at.xml"),
+                    new File(outDir, "team2.at.xml")};
+            File pdffile = new File(outDir, "ResultConcat.pdf");
+            for (int i = 0; i < files.length; i++) {
+                System.out.println("Intermediate file " + (i + 1) + ": " 
+                        + files[i].getCanonicalPath());
+            }
+            System.out.println("PDF Output File: " + pdffile.getCanonicalPath());
+            System.out.println();
+            
+
+            ProjectTeam team1 = ExampleObj2XML.createSampleProjectTeam();
+            ProjectTeam team2 = createAnotherProjectTeam();
+            
+            ExampleConcat app = new ExampleConcat();
+            
+            //Create intermediate files
+            app.convertToIntermediate(
+                    team1.getSourceForProjectTeam(), 
+                    new StreamSource(xsltfile), files[0]);
+            app.convertToIntermediate(
+                    team2.getSourceForProjectTeam(), 
+                    new StreamSource(xsltfile), files[1]);
+            
+            //Concatenate the individual intermediate files to one document
+            app.concatToPDF(files, pdffile);
+            
+            System.out.println("Success!");
+            
+        } catch (Exception e) {
+            e.printStackTrace(System.err);
+            System.exit(-1);
+        }
+    }
+
+}
diff --git a/examples/mathml/src/org/apache/fop/mathml/MathMLElementMapping.java b/examples/mathml/src/org/apache/fop/mathml/MathMLElementMapping.java
index 144d970be..4f0d21d2e 100644
--- a/examples/mathml/src/org/apache/fop/mathml/MathMLElementMapping.java
+++ b/examples/mathml/src/org/apache/fop/mathml/MathMLElementMapping.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 1999-2004 The Apache Software Foundation.
+ * Copyright 1999-2004,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.
@@ -22,6 +22,7 @@ import org.apache.fop.fo.FONode;
 import org.apache.fop.fo.ElementMapping;
 import org.apache.fop.image.analyser.XMLReader;
 import org.apache.fop.image.FopImage;
+import org.w3c.dom.DOMImplementation;
 import org.w3c.dom.Document;
 
 import java.util.HashMap;
@@ -37,10 +38,17 @@ public class MathMLElementMapping extends ElementMapping {
     /** MathML Namespace */
     public static final String NAMESPACE = "http://www.w3.org/1998/Math/MathML"; 
 
+    /** Main constructor. */
     public MathMLElementMapping() {
         this.namespaceURI = NAMESPACE;
     }
 
+    /** @see org.apache.fop.fo.ElementMapping#getDOMImplementation() */
+    public DOMImplementation getDOMImplementation() {
+        return getDefaultDOMImplementation();
+    }
+
+    /** @see org.apache.fop.fo.ElementMapping#initialize() */
     protected void initialize() {
         if (foObjs == null) {
             foObjs = new HashMap();
diff --git a/examples/plan/src/org/apache/fop/plan/PlanElementMapping.java b/examples/plan/src/org/apache/fop/plan/PlanElementMapping.java
index 13d65a3f7..94c6127e5 100644
--- a/examples/plan/src/org/apache/fop/plan/PlanElementMapping.java
+++ b/examples/plan/src/org/apache/fop/plan/PlanElementMapping.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 1999-2004 The Apache Software Foundation.
+ * Copyright 1999-2004,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.
@@ -22,10 +22,9 @@ import org.apache.fop.fo.FONode;
 import org.apache.fop.fo.ElementMapping;
 import org.apache.fop.image.analyser.XMLReader;
 import org.apache.fop.image.FopImage;
+import org.w3c.dom.DOMImplementation;
 import org.w3c.dom.Document;
 
-import java.util.HashMap;
-
 /**
  * This class provides the element mapping for FOP.
  */
@@ -34,10 +33,17 @@ public class PlanElementMapping extends ElementMapping {
     /** Plan Namespace */
     public static final String NAMESPACE = "http://xmlgraphics.apache.org/fop/plan"; 
 
+    /** Main constructor. */
     public PlanElementMapping() {
         this.namespaceURI = NAMESPACE;
     }
 
+    /** @see org.apache.fop.fo.ElementMapping#getDOMImplementation() */
+    public DOMImplementation getDOMImplementation() {
+        return getDefaultDOMImplementation();
+    }
+
+    /** @see org.apache.fop.fo.ElementMapping#initialize() */
     protected void initialize() {
         if (foObjs == null) {
             foObjs = new java.util.HashMap();