Added getPageViewportProvider().

Code styling and javadocs.

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

diff --git a/src/java/org/apache/fop/layoutmgr/PageSequenceLayoutManager.java b/src/java/org/apache/fop/layoutmgr/PageSequenceLayoutManager.java
index 07e6dfdd8e59f06b5788012da8f78fe65dbb1cb9..049811461b7440375b4a04e7989e063ad664bcbf 100644 (file)
--- a/src/java/org/apache/fop/layoutmgr/PageSequenceLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/PageSequenceLayoutManager.java
@@ -103,6 +103,11 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
         return areaTreeHandler.getLayoutManagerMaker();
     }
 
+    /** @return the PageViewportProvider applicable to this page-sequence. */
+    public PageViewportProvider getPageViewportProvider() {
+        return this.pvProvider;
+    }
+    
     /**
      * Activate the layout of this page sequence.
      * PageViewports corresponding to each page generated by this 
@@ -146,7 +151,6 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
         private boolean firstPart = true;
         
         private StaticContentLayoutManager footnoteSeparatorLM = null;
-        private LinkedList footnoteSeparatorList = null;
 
         public PageBreaker(PageSequenceLayoutManager pslm) {
             this.pslm = pslm;
@@ -190,9 +194,11 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
                         // store the lists of elements representing the footnote bodies
                         // in the box representing the line containing their references
                         while (footnoteBodyIterator.hasNext()) {
-                            FootnoteBodyLayoutManager fblm = (FootnoteBodyLayoutManager) footnoteBodyIterator.next();
+                            FootnoteBodyLayoutManager fblm 
+                                = (FootnoteBodyLayoutManager) footnoteBodyIterator.next();
                             fblm.setParent(childFLM);
-                            ((KnuthBlockBox) element).addElementList(fblm.getNextKnuthElements(context, alignment));
+                            ((KnuthBlockBox) element).addElementList(
+                                    fblm.getNextKnuthElements(context, alignment));
                         }
                     }
                 }
@@ -201,7 +207,8 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
             // handle the footnote separator
             StaticContent footnoteSeparator;
             if (bFootnotesPresent
-                && (footnoteSeparator = pageSeq.getStaticContent("xsl-footnote-separator")) != null) {
+                    && (footnoteSeparator = pageSeq.getStaticContent(
+                                            "xsl-footnote-separator")) != null) {
                 // the footnote separator can contain page-dependent content such as
                 // page numbers or retrieve markers, so its areas cannot simply be 
                 // obtained now and repeated in each page;
@@ -233,7 +240,8 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
         
         protected void addAreas(PositionIterator posIter, LayoutContext context) {
             if (footnoteSeparatorLM != null) {
-                StaticContent footnoteSeparator = pageSeq.getStaticContent("xsl-footnote-separator");
+                StaticContent footnoteSeparator = pageSeq.getStaticContent(
+                        "xsl-footnote-separator");
                 // create a Block area that will contain the separator areas
                 separatorArea = new Block();
                 separatorArea.setIPD(curPV.getCurrentSpan().getColumnWidth());
@@ -285,13 +293,16 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
                 // call addAreas() for each FootnoteBodyLM
                 for (int i = pbp.footnoteFirstListIndex; i <= pbp.footnoteLastListIndex; i++) {
                     LinkedList elementList = alg.getFootnoteList(i);
-                    int firstIndex = (i == pbp.footnoteFirstListIndex ? pbp.footnoteFirstElementIndex : 0);
-                    int lastIndex = (i == pbp.footnoteLastListIndex ? pbp.footnoteLastElementIndex : elementList.size() - 1);
+                    int firstIndex = (i == pbp.footnoteFirstListIndex 
+                            ? pbp.footnoteFirstElementIndex : 0);
+                    int lastIndex = (i == pbp.footnoteLastListIndex 
+                            ? pbp.footnoteLastElementIndex : elementList.size() - 1);
 
                     FootnoteBodyLayoutManager fblm = (FootnoteBodyLayoutManager)
-                                                     ((KnuthElement) elementList.getFirst()).getLayoutManager();
+                            ((KnuthElement) elementList.getFirst()).getLayoutManager();
                     LayoutContext childLC = new LayoutContext(0);
-                    fblm.addAreas(new KnuthPossPosIter(elementList, firstIndex, lastIndex + 1), childLC);
+                    fblm.addAreas(new KnuthPossPosIter(elementList, firstIndex, lastIndex + 1), 
+                            childLC);
                 }
                 // set the offset from the top margin
                 Footnote parentArea = (Footnote) getCurrentPV().getBodyRegion().getFootnote();
@@ -538,11 +549,9 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
         if (curPV.getPage().isEmpty()) {
             if (breakVal == Constants.EN_PAGE) {
                 return false;
-            }
-            else if (currentPageNum % 2 == 0) { // even page
+            } else if (currentPageNum % 2 == 0) { // even page
                 return (breakVal == Constants.EN_ODD_PAGE);
-            }
-            else { // odd page
+            } else { // odd page
                 return (breakVal == Constants.EN_EVEN_PAGE);
             }
         } else {
@@ -551,24 +560,52 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
     }
     
     
+    /**
+     * <p>This class delivers PageViewport instances. It also caches them as necessary.
+     * </p>
+     * <p>Additional functionality makes sure that surplus instances that are requested by the
+     * page breaker are properly discarded, especially in situations where hard breaks cause
+     * blank pages. The reason for that: The page breaker sometimes needs to preallocate 
+     * additional pages since it doesn't know exactly until the end how many pages it really needs.
+     * </p>
+     */
     public class PageViewportProvider {
         
+        /** Indices are evaluated relative to the first page in the page-sequence. */
         public static final int RELTO_PAGE_SEQUENCE = 0;
+        /** Indices are evaluated relative to the first page in the current element list. */
         public static final int RELTO_CURRENT_ELEMENT_LIST = 1;
         
         private int startPageOfPageSequence;
         private int startPageOfCurrentElementList;
         private List cachedPageViewports = new java.util.ArrayList();
         
+        /**
+         * Main constructor.
+         * @param ps The page-sequence the provider operates on
+         */
         public PageViewportProvider(PageSequence ps) {
             this.startPageOfPageSequence = ps.getStartingPageNumber();
         }
         
+        /**
+         * The page breaker notifies the provider about the page number an element list starts
+         * on so it can later retrieve PageViewports relative to this first page.
+         * @param startPage the number of the first page for the element list.
+         */
         public void setStartPageOfNextElementList(int startPage) {
             log.debug("start page of the next element list is: " + startPage);
             this.startPageOfCurrentElementList = startPage;
         }
         
+        /**
+         * Returns a PageViewport.
+         * @param bIsBlank true if this page is supposed to be blank.
+         * @param index Index of the page (see relativeTo)
+         * @param relativeTo Defines which value the index parameter should be evaluated relative 
+         * to. (One of PageViewportProvider.RELTO_*)
+         * @return the requested PageViewport
+         */
         public PageViewport getPageViewport(boolean bIsBlank, int index, int relativeTo) {
             if (relativeTo == RELTO_PAGE_SEQUENCE) {
                 return getPageViewport(bIsBlank, index);
@@ -583,15 +620,19 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
         }
         
         private PageViewport getPageViewport(boolean bIsBlank, int index) {
-            //System.out.println("getPageViewport(" + index + " " + bIsBlank);
-            log.debug("getPageViewport(" + index + " " + bIsBlank);
+            if (log.isTraceEnabled()) {
+                log.trace("getPageViewport(" + index + " " + bIsBlank);
+            }
             int intIndex = index - startPageOfPageSequence;
-            if (bIsBlank) {
-                log.debug("blank page requested: " + index);
+            if (log.isTraceEnabled()) {
+                if (bIsBlank) {
+                    log.trace("blank page requested: " + index);
+                }
             }
             while (intIndex >= cachedPageViewports.size()) {
-                //System.out.println("Caching " + index);
-                log.debug("Caching " + index);
+                if (log.isTraceEnabled()) {
+                    log.trace("Caching " + index);
+                }
                 cacheNextPageViewport(index, bIsBlank);
             }
             PageViewport pv = (PageViewport)cachedPageViewports.get(intIndex);
@@ -604,7 +645,6 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
                     }
                 }
                 cacheNextPageViewport(index, bIsBlank);
-                //throw new IllegalStateException("blank condition doesn't match. Check code!");
             }
             return pv;
         }