1.) Driver constructor modified to require RenderType, and setter functions

for RenderType and FOUserAgent removed, to allow for better checking of
a valid Driver object at time of construction.  (Also, will reduce need to
validate Driver object should it be a parameter to a method.)

2.) Added validity checking of renderType to FOTreeBuilder as well, in
effect decoupling Driver from FOTreeBuilder (the latter can work on its own
now.)

3.) Updated the various examples and the documentation to indicate the
new API.


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

2 files changed, 41 insertions, 58 deletions

diff --git a/src/java/org/apache/fop/apps/Driver.java b/src/java/org/apache/fop/apps/Driver.java
index 353eac05f..72d9185ee 100644
--- a/src/java/org/apache/fop/apps/Driver.java
+++ b/src/java/org/apache/fop/apps/Driver.java
@@ -28,7 +28,7 @@ import org.xml.sax.InputSource;
 import org.xml.sax.SAXException;
 import org.xml.sax.XMLReader;
 import org.xml.sax.helpers.DefaultHandler;
-
+   
 // FOP
 import org.apache.fop.fo.Constants;
 import org.apache.fop.fo.FOTreeBuilder;
@@ -41,20 +41,9 @@ import org.apache.fop.fo.FOTreeBuilder;
  * for samples (these are also available within the distribution in 
  * FOP_DIR\examples\embedding)
  * <P>
- * If necessary, calling classes can call into the lower level
- * methods to setup and
- * render. Methods within FOUserAgent can be called to set the
- * Renderer to use, the (possibly multiple) ElementMapping(s) to
- * use and the OutputStream to use to output the results of the
- * rendering (where applicable).
- * <P>
- * Here is an example use of Driver which outputs to AWT:
- *
- * <PRE>
- * Driver driver = new Driver();
- * driver.setRenderer(RENDER_AWT);
- * driver.render(parser, fileInputSource(args[0]));
- * </PRE>
+ * Methods within FOUserAgent are available to customize portions of the
+ * process.  Specific Renderer object can be specified, also ElementMappings
+ * (which determine elements in the FO that can be processed) can be added.
  */
 public class Driver implements Constants {
 
@@ -74,27 +63,49 @@ public class Driver implements Constants {
     private FOUserAgent foUserAgent = null;
 
     /**
-     * Main constructor for the Driver class.
+     * Constructor for use with already-created FOUserAgents
+     * @param renderType the type of renderer to use.  Must be one of
+     * <ul>
+     * <li>Driver.RENDER_PDF</li>
+     * <li>Driver.RENDER_AWT</li>
+     * <li>Driver.RENDER_PRINT</li>
+     * <li>Driver.RENDER_MIF</li>
+     * <li>Driver.RENDER_XML</li>
+     * <li>Driver.RENDER_PCL</li>
+     * <li>Driver.RENDER_PS</li>
+     * <li>Driver.RENDER_TXT</li>
+     * <li>Driver.RENDER_SVG</li>
+     * <li>Driver.RENDER_RTF</li>
+     * </ul>
+     * @param ua FOUserAgent object
+     * @throws IllegalArgumentException if an unsupported renderer type was requested.
      */
-    public Driver() {
-        foUserAgent = new FOUserAgent();
-    }
+    public Driver(int renderType, FOUserAgent ua) {
+        if (renderType == Constants.NOT_SET) {
+            throw new IllegalArgumentException(
+                    "Desired render type not set.");
+        }
+        
+        if (renderType < Constants.RENDER_MIN_CONST 
+            || renderType > Constants.RENDER_MAX_CONST) {
+            throw new IllegalArgumentException(
+                "Invalid render type #" + renderType);
+        }
+
+        this.renderType = renderType;
 
-    /**
-     * Constructor with FOUserAgent
-     * Used by CLI, AWTRenderer
-     */
-    public Driver(FOUserAgent ua) {
         foUserAgent = ua;
+        if (foUserAgent == null) {
+            foUserAgent = new FOUserAgent();
+        }
     }
 
     /**
-     * Optionally sets the FOUserAgent instance for FOP to use. The Driver
-     * class sets up its own FOUserAgent if none is set through this method.
-     * @param agent FOUserAgent to use
+     * Constructor that creates a default FOUserAgent
+     * @see org.apache.fop.apps.Driver#(int, FOUserAgent)
      */
-    public void setUserAgent(FOUserAgent agent) throws FOPException {
-        foUserAgent = agent;
+    public Driver(int renderType) {
+        this(renderType, new FOUserAgent());
     }
 
     /**
@@ -115,33 +126,6 @@ public class Driver implements Constants {
     }
 
     /**
-     * Method to set the rendering type desired. Must be one of
-     * <ul>
-     * <li>Driver.RENDER_PDF</li>
-     * <li>Driver.RENDER_AWT</li>
-     * <li>Driver.RENDER_PRINT</li>
-     * <li>Driver.RENDER_MIF</li>
-     * <li>Driver.RENDER_XML</li>
-     * <li>Driver.RENDER_PCL</li>
-     * <li>Driver.RENDER_PS</li>
-     * <li>Driver.RENDER_TXT</li>
-     * <li>Driver.RENDER_SVG</li>
-     * <li>Driver.RENDER_RTF</li>
-     * </ul>
-     * @param renderType the type of renderer to use
-     * @throws IllegalArgumentException if an unsupported renderer type was requested.
-     */
-    public void setRenderer(int renderType) throws IllegalArgumentException {
-        if (renderType < RENDER_MIN_CONST || renderType > RENDER_MAX_CONST) {
-            renderType = NOT_SET;
-            throw new IllegalArgumentException(
-                "Invalid render ID#" + renderType);
-        }
-
-        this.renderType = renderType;
-    }
-
-    /**
      * Determines which SAX ContentHandler is appropriate for the renderType.
      * Structure renderers (e.g. MIF & RTF) each have a specialized
      * ContentHandler that directly place data into the output stream. Layout
diff --git a/src/java/org/apache/fop/apps/Fop.java b/src/java/org/apache/fop/apps/Fop.java
index d42424fa0..c8e40d1db 100644
--- a/src/java/org/apache/fop/apps/Fop.java
+++ b/src/java/org/apache/fop/apps/Fop.java
@@ -44,8 +44,7 @@ public class Fop {
             options = new CommandLineOptions(args);
             foUserAgent = options.getFOUserAgent();
             
-            Driver driver = new Driver(foUserAgent);
-            driver.setRenderer(options.getRenderer());
+            Driver driver = new Driver(options.getRenderer(), foUserAgent);
 
             try {
                 if (options.getOutputFile() != null) {