clean up documentation of new code and some checkstyle problems

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

diff --git a/src/java/org/apache/fop/apps/Driver.java b/src/java/org/apache/fop/apps/Driver.java
index e21624c27e397ef8a41fcba18c1ef1e24b737a34..d4f1c9782d51ed201dbfbc41bba70e3fdbd29410 100644 (file)
--- a/src/java/org/apache/fop/apps/Driver.java
+++ b/src/java/org/apache/fop/apps/Driver.java
@@ -594,6 +594,19 @@ public class Driver implements LogEnabled, FOTreeListener {
                 //this.atModel = new CachedRenderPagesModel(renderer);
                 areaTree.setTreeModel(atModel);
             }
+            /**
+             The following statement triggers virtually all of the processing
+             for this document. The SAX parser fires events that are handled by
+             the appropriate InputHandler object, which means that you will need
+             to look in those objects to see where FOP picks up control of
+             processing again. For Structure Renderers (e.g. MIF & RTF), the SAX
+             events are handled directly. For Layout Renderers (e.g. PDF &
+             PostScript), an FO Tree is built by the FOTreeHandler, which in
+             turn fires events when a PageSequence object is complete. This
+             allows higher-level control objects (such as this class) to work
+             directly with PageSequence objects. See foPageSequenceComplete()
+             where this level of control is implemented.
+             */
             parser.parse(source);
             if (foInputHandler instanceof FOTreeHandler) {
                 FOTreeHandler foTreeHandler = (FOTreeHandler)foInputHandler;
@@ -659,7 +672,13 @@ public class Driver implements LogEnabled, FOTreeListener {
         }
     }
 
-    public void foPageSequenceComplete (FOTreeEvent event) throws FOPException{
+    /**
+     * Required by the FOTreeListener interface. It handles an
+     * FOTreeEvent that is fired when a PageSequence object has been completed.
+     * @param event the FOTreeEvent that was fired
+     * @throws FOPException for errors in building the PageSequence
+     */
+    public void foPageSequenceComplete (FOTreeEvent event) throws FOPException {
         PageSequence pageSeq = event.getPageSequence();
         Title title = null;
         if (pageSeq.getTitleFO() != null) {
@@ -669,13 +688,19 @@ public class Driver implements LogEnabled, FOTreeListener {
         pageSeq.format(areaTree);
     }
 
-    public void foDocumentComplete (FOTreeEvent event) throws SAXException{
+    /**
+     * Required by the FOTreeListener interface. It handles an FOTreeEvent that
+     * is fired when the Document has been completely parsed.
+     * @param event the FOTreeEvent that was fired
+     * @throws SAXException for parsing errors
+     */
+    public void foDocumentComplete (FOTreeEvent event) throws SAXException {
         //processAreaTree(atModel);
         try {
             areaTree.endDocument();
             renderer.stopRenderer();
-        }
-        catch (IOException ex) {
+        } catch (IOException ex) {
+            throw new SAXException(ex);
         }
     }
 

diff --git a/src/java/org/apache/fop/fo/FOTreeEvent.java b/src/java/org/apache/fop/fo/FOTreeEvent.java
index cf3823495360ef1a6a9375275fbbc86aca586dfb..9c7361acef7ca97f77f43d1128cd8ce943a9f522 100644 (file)
--- a/src/java/org/apache/fop/fo/FOTreeEvent.java
+++ b/src/java/org/apache/fop/fo/FOTreeEvent.java
@@ -66,13 +66,25 @@ public class FOTreeEvent extends EventObject {
 
     private PageSequence pageSeq;
 
+    /**
+     * Constructor captures the object that fired the event.
+     * @param source the Object that fired the event.
+     */
     public FOTreeEvent (Object source) {
         super(source);
     }
 
+    /**
+     * Sets the PageSequence object for this event.
+     * @param pageSeq the PageSequence object attached to this event.
+     */
     public void setPageSequence(PageSequence pageSeq) {
         this.pageSeq = pageSeq;
     }
+
+    /**
+     * @return the PageSequence object attached to this event.
+     */
     public PageSequence getPageSequence () {
         return pageSeq;
     }

diff --git a/src/java/org/apache/fop/fo/FOTreeListener.java b/src/java/org/apache/fop/fo/FOTreeListener.java
index d81759d82439c12818793d4feb9b83c4888bee3b..95201efae1b902e9a7a44cc65b4876f0b55265cf 100644 (file)
--- a/src/java/org/apache/fop/fo/FOTreeListener.java
+++ b/src/java/org/apache/fop/fo/FOTreeListener.java
@@ -60,15 +60,29 @@ import org.xml.sax.SAXException;
 import org.apache.fop.apps.FOPException;
 
 /**
- * An Event used for notification that various stages of the building of an
- * FO tree have been completed. Specifically, these are currently used to
- * notify Driver when a PageSequence has been completed.
+ * An interface for classes that need to handle FOTreeEvent objects as they
+ * are fired.
+ * The key benefit to using this interface is that the implementation can handle
+ * PageSequence objects at a higher level, rather than dealing directly with
+ * a lower-level SAX event.
+ * @see FOTreeEvent
  */
 
 public interface FOTreeListener extends EventListener {
 
-    abstract void foPageSequenceComplete (FOTreeEvent e) throws FOPException;
-    abstract void foDocumentComplete (FOTreeEvent e) throws SAXException;
+    /**
+     * Method for handling a completed PageSequence object.
+     * @param e the FOTreeEvent that has been fired
+     * @throws FOPException for invalid input
+     */
+    void foPageSequenceComplete (FOTreeEvent e) throws FOPException;
+
+    /**
+     * Method for handling the end of the document.
+     * @param e the FOTreeEvent that has been fired
+     * @throws SAXException for parsing error
+     */
+    void foDocumentComplete (FOTreeEvent e) throws SAXException;
 
 }