More code commenting and minor cleanup of bookmark/Resolvable/ATH code.

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

9 files changed, 45 insertions, 59 deletions

diff --git a/src/java/org/apache/fop/area/AreaTreeHandler.java b/src/java/org/apache/fop/area/AreaTreeHandler.java
index 86611034c..68ac04914 100644
--- a/src/java/org/apache/fop/area/AreaTreeHandler.java
+++ b/src/java/org/apache/fop/area/AreaTreeHandler.java
@@ -51,7 +51,7 @@ import org.apache.fop.layoutmgr.PageSequenceLayoutManager;
  * The area tree needs to be simple to render and follow the spec
  * closely.
  * This area tree has the concept of page sequences.
- * Where ever possible information is discarded or optimized to
+ * Wherever possible information is discarded or optimized to
  * keep memory use low. The data is also organized to make it
  * possible for renderers to minimize their output.
  * A page can be saved if not fully resolved and once rendered
@@ -82,11 +82,12 @@ public class AreaTreeHandler extends FOEventHandler {
     // The fo:root node of the document
     private Root rootFObj;
 
-    // HashMap of ID's whose area is located on one or more PageViewports
-    // Each ID has an arraylist of PageViewports sharing the area with this ID
+    // HashMap of ID's whose area is located on one or more consecutive 
+    // PageViewports.  Each ID has an arraylist of PageViewports that
+    // form the defined area of this ID
     private Map idLocations = new HashMap();
 
-    // idref's whose corresponding id's have yet to be found
+    // idref's whose target PageViewports have yet to be identified
     // Each idref has a HashSet of Resolvable objects containing that idref
     private Map unresolvedIDRefs = new HashMap();
 
@@ -136,8 +137,9 @@ public class AreaTreeHandler extends FOEventHandler {
             idLocations.put(id, pvList);
             pvList.add(pv);
 
-            /* See if this ID is in the unresolved idref list.  Note:
-             * unresolving occurs at first PV found for a given area. 
+            /* 
+             * See if this ID is in the unresolved idref list, if so
+             * resolve Resolvable objects tied to it.
              */
             Set todo = (Set) unresolvedIDRefs.get(id);
             if (todo != null) {
@@ -237,7 +239,6 @@ public class AreaTreeHandler extends FOEventHandler {
             PageSequenceLayoutManager pageSLM 
                 = new PageSequenceLayoutManager(this, pageSequence);
             pageSLM.activateLayout();
-            pageSequence.setCurrentPageNumber(pageSLM.getPageCount());
         }
     }
 
@@ -285,7 +286,7 @@ public class AreaTreeHandler extends FOEventHandler {
     private void addOffDocumentItem(OffDocumentItem odi) {
         if (odi instanceof Resolvable) {
             Resolvable res = (Resolvable) odi;
-            String[] ids = res.getIDs();
+            String[] ids = res.getIDRefs();
             for (int count = 0; count < ids.length; count++) {
                 if (idLocations.containsKey(ids[count])) {
                     res.resolveIDRef(ids[count], (List) idLocations.get(ids[count]));
diff --git a/src/java/org/apache/fop/area/BookmarkData.java b/src/java/org/apache/fop/area/BookmarkData.java
index 5384a7cdf..9e814a0d9 100644
--- a/src/java/org/apache/fop/area/BookmarkData.java
+++ b/src/java/org/apache/fop/area/BookmarkData.java
@@ -23,8 +23,9 @@ import java.util.List;
 import java.util.HashMap;
 
 /**
- * An instance of this class is either a PDF bookmark OffDocumentItem and
- * its child bookmarks.
+ * An instance of this class is either a PDF bookmark-tree and
+ * its child bookmark-items, or a bookmark-item and the child
+ * child bookmark-items under it.
  */
 public class BookmarkData extends OffDocumentItem implements Resolvable {
     private ArrayList subData = new ArrayList();
@@ -43,9 +44,8 @@ public class BookmarkData extends OffDocumentItem implements Resolvable {
 
     /**
      * Create a new bookmark data object.
-     * This should only be call by the top level element as its
-     * idref will be null.
-     *
+     * This should only be called by the bookmark-tree item because
+     * it has no idref item that needs to be resolved.
      */
     public BookmarkData() {
         idRef = null;
@@ -54,22 +54,23 @@ public class BookmarkData extends OffDocumentItem implements Resolvable {
 
     /**
      * Create a new pdf bookmark data object.
-     * This is used by the outlines to create a data object
-     * with a id reference. The id reference is to be resolved.
+     * This is used by the bookmark-items to create a data object
+     * with a idref.  During processing, this idref will be
+     * subsequently resolved to a particular PageViewport.
      *
-     * @param id the id reference
+     * @param idref the id reference
      */
-    public BookmarkData(String id) {
-        idRef = id;
+    public BookmarkData(String idref) {
+        this.idRef = idref;
         unresolvedIDRefs.put(idRef, this);
     }
 
     /**
-     * Get the id reference for this data.
+     * Get the idref for this bookmark-item
      *
-     * @return the id reference
+     * @return the idref for the bookmark-item
      */
-    public String getID() {
+    public String getIDRef() {
         return idRef;
     }
 
@@ -81,8 +82,8 @@ public class BookmarkData extends OffDocumentItem implements Resolvable {
      */
     public void addSubData(BookmarkData sub) {
         subData.add(sub);
-        unresolvedIDRefs.put(sub.getID(), sub);
-        String[] ids = sub.getIDs();
+        unresolvedIDRefs.put(sub.getIDRef(), sub);
+        String[] ids = sub.getIDRefs();
         for (int count = 0; count < ids.length; count++) {
             unresolvedIDRefs.put(ids[count], sub);
         }
@@ -136,63 +137,46 @@ public class BookmarkData extends OffDocumentItem implements Resolvable {
 
     /**
      * Check if this resolvable object has been resolved.
-     * Once the id reference is null then it has been resolved.
+     * A BookmarkData object is considered resolved once the idrefs for it
+     * and for all of its child bookmark-items have been resolved.
      *
-     * @return true if this has been resolved
+     * @return true if this object has been resolved
      */
     public boolean isResolved() {
-        return unresolvedIDRefs == null;
+        return unresolvedIDRefs == null || (unresolvedIDRefs.size() == 0);
     }
 
     /**
-     * Get the id references held by this object.
-     * Also includes all id references of all children.
-     *
-     * @return the array of id references
+     * @see org.apache.fop.area.Resolvable#getIDRefs()
      */
-    public String[] getIDs() {
+    public String[] getIDRefs() {
         return (String[])unresolvedIDRefs.keySet().toArray(new String[] {});
     }
 
     /**
      * Resolve this resolvable object.
-     * This resolves the id reference and if possible also
+     * This resolves the idref of this object and if possible also
      * resolves id references of child elements that have the same
      * id reference.
      *
-     * @param id the ID which has already been resolved to one or more
-     *      PageViewport objects
-     * @param pages the list of PageViewport objects the ID resolves to
+     * @see org.apache.fop.area.Resolvable#resolveIDRef(String, List)
+     * @todo check to make sure works when multiple bookmark-items
+     * have the same idref
      */
     public void resolveIDRef(String id, List pages) {
-        // this method is buggy
         if (!id.equals(idRef)) {
-            BookmarkData bd = (BookmarkData)unresolvedIDRefs.get(id);
-            unresolvedIDRefs.remove(id);
+            BookmarkData bd = (BookmarkData) unresolvedIDRefs.get(id);
             if (bd != null) {
                 bd.resolveIDRef(id, pages);
-                if (bd.isResolved()) {
-                    checkFinish();
-                }
-            } else if (idRef == null) {
-                checkFinish();
+                unresolvedIDRefs.remove(id);
             }
         } else {
-            if (pages != null) {
-                pageRef = (PageViewport)pages.get(0);
-            }
+            pageRef = (PageViewport) pages.get(0);
             // TODO get rect area of id on page
             unresolvedIDRefs.remove(idRef);
-            checkFinish();
         }
     }
 
-    private void checkFinish() {
-        if (unresolvedIDRefs.size() == 0) {
-            unresolvedIDRefs = null;
-        }
-    }
-    
     /**
      * @see org.apache.fop.area.OffDocumentItem#getName()
      */
diff --git a/src/java/org/apache/fop/area/CachedRenderPagesModel.java b/src/java/org/apache/fop/area/CachedRenderPagesModel.java
index 18e003cb9..d09f00001 100644
--- a/src/java/org/apache/fop/area/CachedRenderPagesModel.java
+++ b/src/java/org/apache/fop/area/CachedRenderPagesModel.java
@@ -81,7 +81,7 @@ public class CachedRenderPagesModel extends RenderPagesModel {
                 try {
                     renderer.renderPage(p);
                     if (!p.isResolved()) {
-                        String[] idrefs = p.getIDs();
+                        String[] idrefs = p.getIDRefs();
                         for (int count = 0; count < idrefs.length; count++) {
                             log.warn("Page " + p.getPageNumber() + 
                                 ": Unresolved id reference \"" + idrefs[count] 
diff --git a/src/java/org/apache/fop/area/LinkResolver.java b/src/java/org/apache/fop/area/LinkResolver.java
index cbc38095a..c3c0830d3 100644
--- a/src/java/org/apache/fop/area/LinkResolver.java
+++ b/src/java/org/apache/fop/area/LinkResolver.java
@@ -54,7 +54,7 @@ public class LinkResolver implements Resolvable, Serializable {
         return resolved;
     }
 
-    public String[] getIDs() {
+    public String[] getIDRefs() {
         return new String[] {idRef};
     }
 
diff --git a/src/java/org/apache/fop/area/PageViewport.java b/src/java/org/apache/fop/area/PageViewport.java
index 94d0b9f94..74a491614 100644
--- a/src/java/org/apache/fop/area/PageViewport.java
+++ b/src/java/org/apache/fop/area/PageViewport.java
@@ -157,7 +157,7 @@ public class PageViewport implements Resolvable, Cloneable {
      * Get the unresolved idrefs for this page.
      * @return String array of idref's that still have not been resolved
      */
-    public String[] getIDs() {
+    public String[] getIDRefs() {
         return (unresolvedIDRefs == null) ? null :
             (String[]) unresolvedIDRefs.keySet().toArray(new String[] {});
     }
diff --git a/src/java/org/apache/fop/area/RenderPagesModel.java b/src/java/org/apache/fop/area/RenderPagesModel.java
index 8a188b99b..c28b7fb61 100644
--- a/src/java/org/apache/fop/area/RenderPagesModel.java
+++ b/src/java/org/apache/fop/area/RenderPagesModel.java
@@ -149,7 +149,7 @@ public class RenderPagesModel extends StorePagesModel {
                 try {
                     renderer.renderPage(p);
                     if (!p.isResolved()) {
-                        String[] idrefs = p.getIDs();
+                        String[] idrefs = p.getIDRefs();
                         for (int count = 0; count < idrefs.length; count++) {
                             log.warn("Page " + p.getPageNumber() + 
                                 ": Unresolved id reference \"" + idrefs[count] 
diff --git a/src/java/org/apache/fop/area/Resolvable.java b/src/java/org/apache/fop/area/Resolvable.java
index 7d1da2c23..e8ad3f791 100644
--- a/src/java/org/apache/fop/area/Resolvable.java
+++ b/src/java/org/apache/fop/area/Resolvable.java
@@ -42,7 +42,7 @@ public interface Resolvable {
      *
      * @return the id references for resolving this object
      */
-    String[] getIDs();
+    String[] getIDRefs();
 
     /**
      * This method allows the Resolvable object to resolve one of
diff --git a/src/java/org/apache/fop/area/inline/UnresolvedPageNumber.java b/src/java/org/apache/fop/area/inline/UnresolvedPageNumber.java
index 30db0d7e8..09115fdf8 100644
--- a/src/java/org/apache/fop/area/inline/UnresolvedPageNumber.java
+++ b/src/java/org/apache/fop/area/inline/UnresolvedPageNumber.java
@@ -47,7 +47,7 @@ public class UnresolvedPageNumber extends TextArea implements Resolvable {
      *
      * @return the id reference for this unresolved page number
      */
-    public String[] getIDs() {
+    public String[] getIDRefs() {
         return new String[] {pageIDRef};
     }
 
diff --git a/src/java/org/apache/fop/layoutmgr/PageSequenceLayoutManager.java b/src/java/org/apache/fop/layoutmgr/PageSequenceLayoutManager.java
index 4ac067b08..4af629500 100644
--- a/src/java/org/apache/fop/layoutmgr/PageSequenceLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/PageSequenceLayoutManager.java
@@ -226,6 +226,7 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
         pageCount--;
         log.debug("Ending layout");
         flush();
+        fobj.setCurrentPageNumber(getPageCount());
     }
 
     /**