Merged Temp_API_Finalization branch back into FOP Trunk:

Finalized API according to the plan in the Wiki: http://wiki.apache.org/xmlgraphics-fop/ApiDesign

In addition to that:
Deprecated the rest of the Fop constructors.
Refactored the FopServlet a bit to make it more versatile and still easy to understand. The FopPrintServlet is now a subclass of FopServlet.
Some further cleanup on the way.

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

2 files changed, 82 insertions, 186 deletions

diff --git a/src/java/org/apache/fop/servlet/FopPrintServlet.java b/src/java/org/apache/fop/servlet/FopPrintServlet.java
index 8ac980ccd..6b3268572 100644
--- a/src/java/org/apache/fop/servlet/FopPrintServlet.java
+++ b/src/java/org/apache/fop/servlet/FopPrintServlet.java
@@ -1,5 +1,5 @@
 /*
- * 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.
@@ -18,25 +18,18 @@
 
 package org.apache.fop.servlet;
 
-import java.io.File;
-import java.io.InputStream;
+import java.io.IOException;
 import java.io.PrintWriter;
 
-// JAXP
-import javax.servlet.ServletException;
-import javax.servlet.http.HttpServlet;
-import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
+
 import javax.xml.transform.Transformer;
-import javax.xml.transform.TransformerFactory;
+import javax.xml.transform.TransformerException;
 import javax.xml.transform.Result;
 import javax.xml.transform.Source;
-import javax.xml.transform.URIResolver;
 import javax.xml.transform.sax.SAXResult;
-import javax.xml.transform.stream.StreamSource;
 
-// XML
-import org.apache.commons.logging.impl.SimpleLog;
+import org.apache.fop.apps.FOPException;
 import org.apache.fop.apps.FOUserAgent;
 import org.apache.fop.apps.Fop;
 import org.apache.fop.apps.MimeConstants;
@@ -58,164 +51,49 @@ import org.apache.fop.apps.MimeConstants;
  * Example URL: http://servername/fop/servlet/FopPrintServlet?fo=readme.fo
  * <br/>
  * Example URL: http://servername/fop/servlet/FopPrintServlet?xml=data.xml&xsl=format.xsl
- *
- * @author <a href="mailto:fop-dev@xml.apache.org">Apache XML FOP Development Team</a>
+ * <br/>
+ * <b>Note:</b> This servlet is derived from FopServlet. Most methods are inherited from the 
+ * superclass. Only the differences to the base class are necessary.
+ * 
+ * @author <a href="mailto:fop-dev@xmlgraphics.apache.org">Apache FOP Development Team</a>
  * @version $Id$
- * (todo) Doesn't work since there's no AWTRenderer at the moment. Revisit when
- * available.
- * (todo) Ev. add caching mechanism for Templates objects
  */
-public class FopPrintServlet extends HttpServlet {
-
-    /** Name of the parameter used for the XSL-FO file */
-    protected static final String FO_REQUEST_PARAM = "fo";
-    /** Name of the parameter used for the XML file */
-    protected static final String XML_REQUEST_PARAM = "xml";
-    /** Name of the parameter used for the XSLT file */
-    protected static final String XSLT_REQUEST_PARAM = "xslt";
-
-    /** Logger to give to FOP */
-    protected SimpleLog log = null;
-    
-    /** The TransformerFactory to use to create Transformer instances */
-    protected TransformerFactory transFactory = null;
-    /** URIResolver for use by this servlet */
-    protected URIResolver uriResolver; 
-
-    /**
-     * @see javax.servlet.GenericServlet#init()
-     */
-    public void init() throws ServletException {
-        this.log = new SimpleLog("FOP/Print Servlet");
-        log.setLevel(SimpleLog.LOG_LEVEL_WARN);
-        this.uriResolver = new ServletContextURIResolver(getServletContext());
-        this.transFactory = TransformerFactory.newInstance();
-        this.transFactory.setURIResolver(this.uriResolver);
-    }
-
-    /**
-     * @see javax.servlet.http.HttpServlet#doGet(HttpServletRequest, HttpServletResponse)
-     */
-    public void doGet(HttpServletRequest request,
-                      HttpServletResponse response) throws ServletException {
-        if (log == null) {
-            log = new SimpleLog("FOP/Print Servlet");
-            log.setLevel(SimpleLog.LOG_LEVEL_WARN);
-        }
-
-        try {
-            String foParam = request.getParameter(FO_REQUEST_PARAM);
-            String xmlParam = request.getParameter(XML_REQUEST_PARAM);
-            String xsltParam = request.getParameter(XSLT_REQUEST_PARAM);
-
-            if (foParam != null) {
-                InputStream file = new java.io.FileInputStream(foParam);
-                renderFO(file, response);
-            } else if ((xmlParam != null) && (xsltParam != null)) {
-                renderXML(new File(xmlParam), new File(xsltParam), response);
-            } else {
-                response.setContentType("text/html");
-
-                PrintWriter out = response.getWriter();
-                out.println("<html><title>Error</title>\n"
-                        + "<body><h1>FopServlet Error</h1>\n"
-                        + "<h3>No 'fo' or 'xml/xsl' "
-                        + "request param given.</h3></body>\n</html>");
-            }
-        } catch (ServletException ex) {
-            throw ex;
-        } catch (Exception ex) {
-            throw new ServletException(ex);
-        }
-    }
-
-    /**
-     * Renders an FO inputsource to the default printer.
-     * @param foFile The XSL-FO file
-     * @param response Response to write to
-     * @throws ServletException In case of a problem
-     */
-    public void renderFO(InputStream foFile,
-                         HttpServletResponse response) throws ServletException {
-        try {
-            Fop fop = new Fop(MimeConstants.MIME_FOP_PRINT, getFOUserAgent());
-
-            // Setup JAXP
-            TransformerFactory factory = TransformerFactory.newInstance();
-            Transformer transformer = factory.newTransformer(); //identity transformer
-            transformer.setURIResolver(this.uriResolver);
-            
-            // Setup input for XSLT transformation
-            Source src = new StreamSource(foFile);
-            
-            // 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);
-            
-            reportOK (response);
-        } catch (Exception ex) {
-            throw new ServletException(ex);
-        }
-    }
+public class FopPrintServlet extends FopServlet {
 
     /**
-     * Renders an FO generated using an XML and a stylesheet to the default printer.
-     * @param xmlfile XML file object
-     * @param xsltfile XSLT stylesheet 
-     * @param response HTTP response object
-     * @throws ServletException In case of a problem
+     * @see org.apache.fop.servlet.FopServlet#render(javax.xml.transform.Source, 
+     *      javax.xml.transform.Transformer, javax.servlet.http.HttpServletResponse)
      */
-    public void renderXML(File xmlfile, File xsltfile,
-                          HttpServletResponse response) throws ServletException {
-        try {
-            Fop fop = new Fop(MimeConstants.MIME_FOP_PRINT, getFOUserAgent());
+    protected void render(Source src, Transformer transformer, HttpServletResponse response)
+            throws FOPException, TransformerException, IOException {
 
-            // Setup XSLT
-            TransformerFactory factory = TransformerFactory.newInstance();
-            Transformer transformer = factory.newTransformer(new StreamSource(xsltfile));
-            transformer.setURIResolver(this.uriResolver);
-            
-            // Setup input for XSLT transformation
-            Source src = new StreamSource(xmlfile);
+        FOUserAgent foUserAgent = getFOUserAgent();
         
-            // 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);
-
-            reportOK (response);
-        } catch (Exception ex) {
-            throw new ServletException(ex);
-        }
+        //Setup FOP
+        Fop fop = fopFactory.newFop(MimeConstants.MIME_FOP_PRINT, foUserAgent);
+        
+        //Make sure the XSL transformation's result is piped through to FOP
+        Result res = new SAXResult(fop.getDefaultHandler());
+        
+        //Start the transformation and rendering process
+        transformer.transform(src, res);
+        
+        //Return the result
+        reportOK(response);
     }
 
     // private helper, tell (browser) user that file printed
-    private void reportOK(HttpServletResponse response)
-                throws ServletException {
+    private void reportOK(HttpServletResponse response) throws IOException {
         String sMsg = "<html><title>Success</title>\n"
                 + "<body><h1>FopPrintServlet: </h1>"
-                + "<h3>The requested data was printed</h3></body></html>";
+                + "<h3>The requested data was printed to the default printer.</h3></body></html>";
 
         response.setContentType("text/html");
         response.setContentLength(sMsg.length());
 
-        try {
-            PrintWriter out = response.getWriter();
-            out.println(sMsg);
-            out.flush();
-        } catch (Exception ex) {
-            throw new ServletException(ex);
-        }
-    }
-
-    /** @return a new FOUserAgent for FOP */
-    protected FOUserAgent getFOUserAgent() {
-        FOUserAgent userAgent = new FOUserAgent();
-        userAgent.setURIResolver(this.uriResolver);
-        return userAgent;
+        PrintWriter out = response.getWriter();
+        out.println(sMsg);
+        out.flush();
     }
 
 }
diff --git a/src/java/org/apache/fop/servlet/FopServlet.java b/src/java/org/apache/fop/servlet/FopServlet.java
index cd1d23014..241c99319 100644
--- a/src/java/org/apache/fop/servlet/FopServlet.java
+++ b/src/java/org/apache/fop/servlet/FopServlet.java
@@ -19,6 +19,7 @@
 package org.apache.fop.servlet;
 
 import java.io.File;
+import java.io.IOException;
 import java.io.PrintWriter;
 
 import javax.servlet.ServletException;
@@ -37,10 +38,10 @@ import javax.xml.transform.stream.StreamSource;
 import org.apache.commons.io.output.ByteArrayOutputStream;
 import org.apache.commons.logging.impl.SimpleLog;
 
-//FOP
 import org.apache.fop.apps.FOUserAgent;
 import org.apache.fop.apps.Fop;
 import org.apache.fop.apps.FOPException;
+import org.apache.fop.apps.FopFactory;
 import org.apache.fop.apps.MimeConstants;
 
 /**
@@ -63,7 +64,7 @@ import org.apache.fop.apps.MimeConstants;
  * For this to work with Internet Explorer, you might need to append "&ext=.pdf"
  * to the URL.
  *
- * @author <a href="mailto:fop-dev@xml.apache.org">Apache XML FOP Development Team</a>
+ * @author <a href="mailto:fop-dev@xmlgraphics.apache.org">Apache FOP Development Team</a>
  * @version $Id$
  * (todo) Ev. add caching mechanism for Templates objects
  */
@@ -78,8 +79,10 @@ public class FopServlet extends HttpServlet {
 
     /** Logger to give to FOP */
     protected SimpleLog log = null;
-    /** The TransformerFactory to use to create Transformer instances */
+    /** The TransformerFactory used to create Transformer instances */
     protected TransformerFactory transFactory = null;
+    /** The FopFactory used to create Fop instances */
+    protected FopFactory fopFactory = null;
     /** URIResolver for use by this servlet */
     protected URIResolver uriResolver; 
 
@@ -92,6 +95,18 @@ public class FopServlet extends HttpServlet {
         this.uriResolver = new ServletContextURIResolver(getServletContext());
         this.transFactory = TransformerFactory.newInstance();
         this.transFactory.setURIResolver(this.uriResolver);
+        //Configure FopFactory as desired
+        this.fopFactory = FopFactory.newInstance();
+        this.fopFactory.setURIResolver(this.uriResolver);
+        configureFopFactory();
+    }
+    
+    /**
+     * This method is called right after the FopFactory is instantiated and can be overridden
+     * by subclasses to perform additional configuration.
+     */
+    protected void configureFopFactory() {
+        //Subclass and override this method to perform additional configuration
     }
 
     /**
@@ -106,26 +121,17 @@ public class FopServlet extends HttpServlet {
             String xsltParam = request.getParameter(XSLT_REQUEST_PARAM);
 
             //Analyze parameters and decide with method to use
-            byte[] content = null;
             if (foParam != null) {
-                content = renderFO(foParam);
+                renderFO(foParam, response);
             } else if ((xmlParam != null) && (xsltParam != null)) {
-                content = renderXML(xmlParam, xsltParam);
+                renderXML(xmlParam, xsltParam, response);
             } else {
+                response.setContentType("text/html");
                 PrintWriter out = response.getWriter();
                 out.println("<html><head><title>Error</title></head>\n"
                           + "<body><h1>FopServlet Error</h1><h3>No 'fo' "
                           + "request param given.</body></html>");
             }
-
-            if (content != null) {
-                //Send the result back to the client
-                response.setContentType("application/pdf");
-                response.setContentLength(content.length);
-                response.getOutputStream().write(content);
-                response.getOutputStream().flush();
-            }
-
         } catch (Exception ex) {
             throw new ServletException(ex);
         }
@@ -140,18 +146,27 @@ public class FopServlet extends HttpServlet {
         return new StreamSource(new File(param));
     }
 
+    private void sendPDF(byte[] content, HttpServletResponse response) throws IOException {
+        //Send the result back to the client
+        response.setContentType("application/pdf");
+        response.setContentLength(content.length);
+        response.getOutputStream().write(content);
+        response.getOutputStream().flush();
+    }
+    
     /**
      * Renders an XSL-FO file into a PDF file. The PDF is written to a byte
      * array that is returned as the method's result.
      * @param fo the XSL-FO file
-     * @return byte[] the rendered PDF file
+     * @param response HTTP response object
      * @throws FOPException If an error occurs during the rendering of the
      * XSL-FO
      * @throws TransformerException If an error occurs while parsing the input
      * file
+     * @throws IOException In case of an I/O problem
      */
-    protected byte[] renderFO(String fo)
-                throws FOPException, TransformerException {
+    protected void renderFO(String fo, HttpServletResponse response)
+                throws FOPException, TransformerException, IOException {
 
         //Setup source
         Source foSrc = convertString2Source(fo);
@@ -161,7 +176,7 @@ public class FopServlet extends HttpServlet {
         transformer.setURIResolver(this.uriResolver);
 
         //Start transformation and rendering process
-        return render(foSrc, transformer);
+        render(foSrc, transformer, response);
     }
 
     /**
@@ -170,14 +185,15 @@ public class FopServlet extends HttpServlet {
      * that is returned as the method's result.
      * @param xml the XML file
      * @param xslt the XSLT file
-     * @return byte[] the rendered PDF file
+     * @param response HTTP response object
      * @throws FOPException If an error occurs during the rendering of the
      * XSL-FO
      * @throws TransformerException If an error occurs during XSL
      * transformation
+     * @throws IOException In case of an I/O problem
      */
-    protected byte[] renderXML(String xml, String xslt)
-                throws FOPException, TransformerException {
+    protected void renderXML(String xml, String xslt, HttpServletResponse response)
+                throws FOPException, TransformerException, IOException {
 
         //Setup sources
         Source xmlSrc = convertString2Source(xml);
@@ -188,7 +204,7 @@ public class FopServlet extends HttpServlet {
         transformer.setURIResolver(this.uriResolver);
 
         //Start transformation and rendering process
-        return render(xmlSrc, transformer);
+        render(xmlSrc, transformer, response);
     }
 
     /**
@@ -199,21 +215,23 @@ public class FopServlet extends HttpServlet {
      * returned as the method's result.
      * @param src Input XML or XSL-FO
      * @param transformer Transformer to use for optional transformation
-     * @return byte[] the rendered PDF file
+     * @param response HTTP response object
      * @throws FOPException If an error occurs during the rendering of the
      * XSL-FO
      * @throws TransformerException If an error occurs during XSL
      * transformation
+     * @throws IOException In case of an I/O problem
      */
-    protected byte[] render(Source src, Transformer transformer)
-                throws FOPException, TransformerException {
+    protected void render(Source src, Transformer transformer, HttpServletResponse response)
+                throws FOPException, TransformerException, IOException {
 
-        //Setup FOP
-        Fop fop = new Fop(MimeConstants.MIME_PDF, getFOUserAgent());
+        FOUserAgent foUserAgent = getFOUserAgent();
 
         //Setup output
         ByteArrayOutputStream out = new ByteArrayOutputStream();
-        fop.setOutputStream(out);
+
+        //Setup FOP
+        Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF, foUserAgent, out);
 
         //Make sure the XSL transformation's result is piped through to FOP
         Result res = new SAXResult(fop.getDefaultHandler());
@@ -222,13 +240,13 @@ public class FopServlet extends HttpServlet {
         transformer.transform(src, res);
 
         //Return the result
-        return out.toByteArray();
+        sendPDF(out.toByteArray(), response);
     }
     
     /** @return a new FOUserAgent for FOP */
     protected FOUserAgent getFOUserAgent() {
-        FOUserAgent userAgent = new FOUserAgent();
-        userAgent.setURIResolver(this.uriResolver);
+        FOUserAgent userAgent = fopFactory.newFOUserAgent();
+        //Configure foUserAgent as desired
         return userAgent;
     }