Fix SO error while iterating struct tree root

DEVSIX-8373

Author: vitali-pr

kernel/src/main/java/com/itextpdf/kernel/pdf/tagging/PdfStructTreeRoot.java

@@ -45,6 +45,10 @@ This file is part of the iText (R) project.
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
+
+import com.itextpdf.kernel.pdf.tagutils.TagTreeIterator;
+import com.itextpdf.kernel.pdf.tagutils.TagTreeIteratorAvoidDuplicatesApprover;
+import com.itextpdf.kernel.pdf.tagutils.TagTreeIteratorFlusher;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -351,7 +355,7 @@ public void flush() {
             getPdfObject().put(PdfName.IDTree, this.idTree.buildTree().makeIndirect(getDocument()));
         }
         if (!getDocument().isAppendMode()) {
-            flushAllKids(this);
+            PdfStructTreeRoot.flushAllKids(this);
         }
         super.flush();
     }
@@ -521,13 +525,11 @@ protected boolean isWrappedObjectMustBeIndirect() {
         return true;
     }
 
-    private void flushAllKids(IStructureNode elem) {
-        for (IStructureNode kid : elem.getKids()) {
-            if (kid instanceof PdfStructElem && !((PdfStructElem) kid).isFlushed()) {
-                flushAllKids(kid);
-                ((PdfStructElem) kid).flush();
-            }
-        }
+    private static void flushAllKids(PdfStructTreeRoot elem) {
+        TagTreeIterator iterator = new TagTreeIterator(
+                elem, new TagTreeIteratorAvoidDuplicatesApprover(), TagTreeIterator.TreeTraversalOrder.POST_ORDER);
+        iterator.addHandler(new TagTreeIteratorFlusher());
+        iterator.traverse();
     }
 
     private void ifKidIsStructElementAddToList(PdfObject kid, List<IStructureNode> kids) {

kernel/src/main/java/com/itextpdf/kernel/pdf/tagutils/ITagTreeIteratorHandler.java

@@ -36,5 +36,4 @@ public interface ITagTreeIteratorHandler {
      * @param elem the next element
      */
     void nextElement(IStructureNode elem);
-
 }

kernel/src/main/java/com/itextpdf/kernel/pdf/tagutils/TagTreeIterator.java

@@ -28,44 +28,74 @@ This file is part of the iText (R) project.
 
 import java.util.HashSet;
 import java.util.List;
-import java.util.Objects;
 import java.util.Set;
 
 /**
  * This class is used to traverse the tag tree.
  * <p>
  *
- * There is a possibility to add a handler that will be called for specific events during the traversal.
+ * There is a possibility to add a handler that will be called for the elements during the traversal.
  */
 public class TagTreeIterator {
 
-
     private final IStructureNode pointer;
 
     private final Set<ITagTreeIteratorHandler> handlerList;
 
+    private final TagTreeIteratorElementApprover approver;
+
+    private final TreeTraversalOrder traversalOrder;
+
     /**
-     * Creates a new instance of {@link TagTreeIterator}.
+     * Creates a new instance of {@link TagTreeIterator}. It will use {@link TagTreeIteratorElementApprover} to filter
+     * elements and TreeTraversalOrder.PRE_ORDER for tree traversal.
      *
      * @param tagTreePointer the tag tree pointer.
      */
     public TagTreeIterator(IStructureNode tagTreePointer) {
+        this(tagTreePointer, new TagTreeIteratorElementApprover(), TreeTraversalOrder.PRE_ORDER);
+    }
+
+    /**
+     * Creates a new instance of {@link TagTreeIterator}.
+     *
+     * @param tagTreePointer the tag tree pointer.
+     * @param approver a filter that will be called to let iterator know whether some particular element
+     *                should be traversed or not.
+     * @param traversalOrder an order in which the tree will be traversed.
+     */
+    public TagTreeIterator(IStructureNode tagTreePointer, TagTreeIteratorElementApprover approver,
+                           TreeTraversalOrder traversalOrder) {
         if (tagTreePointer == null) {
             throw new IllegalArgumentException(
                     MessageFormatUtil.format(KernelExceptionMessageConstant.ARG_SHOULD_NOT_BE_NULL, "tagTreepointer"));
         }
+        if (approver == null) {
+            throw new IllegalArgumentException(
+                    MessageFormatUtil.format(KernelExceptionMessageConstant.ARG_SHOULD_NOT_BE_NULL, "approver"));
+        }
+        if (traversalOrder == null) {
+            throw new IllegalArgumentException(
+                    MessageFormatUtil.format(KernelExceptionMessageConstant.ARG_SHOULD_NOT_BE_NULL, "traversalOrder"));
+        }
         this.pointer = tagTreePointer;
+        this.traversalOrder = traversalOrder;
         handlerList = new HashSet<>();
+        this.approver = approver;
     }
 
     /**
-     * Adds a handler that will be called for specific events during the traversal.
+     * Adds a handler that will be called for the elements during the traversal.
      *
      * @param handler the handler.
      *
      * @return this {@link TagTreeIterator} instance.
      */
     public TagTreeIterator addHandler(ITagTreeIteratorHandler handler) {
+        if (handler == null) {
+            throw new IllegalArgumentException(
+                    MessageFormatUtil.format(KernelExceptionMessageConstant.ARG_SHOULD_NOT_BE_NULL, "handler"));
+        }
         this.handlerList.add(handler);
         return this;
     }
@@ -77,22 +107,45 @@ public TagTreeIterator addHandler(ITagTreeIteratorHandler handler) {
      * Make sure the correct handlers are added before calling this method.
      */
     public void traverse() {
-        traverse(this.pointer, this.handlerList);
+        traverse(this.pointer);
     }
 
-    private static void traverse(IStructureNode elem, Set<ITagTreeIteratorHandler> handlerList) {
-        if (elem == null) {
+    private void traverse(IStructureNode elem) {
+        if (!approver.approve(elem)) {
             return;
         }
-        for (ITagTreeIteratorHandler handler : handlerList) {
-            handler.nextElement(elem);
+
+        if (traversalOrder == TreeTraversalOrder.PRE_ORDER) {
+            for (ITagTreeIteratorHandler handler : handlerList) {
+                handler.nextElement(elem);
+            }
         }
+
         List<IStructureNode> kids = elem.getKids();
         if (kids != null) {
             for (IStructureNode kid : kids) {
-                traverse(kid, handlerList);
+                traverse(kid);
+            }
+        }
+
+        if (traversalOrder == TreeTraversalOrder.POST_ORDER) {
+            for (ITagTreeIteratorHandler handler : handlerList) {
+                handler.nextElement(elem);
             }
         }
     }
 
+    /**
+     * Tree traversal order enum.
+     */
+    public enum TreeTraversalOrder {
+        /**
+         * Preorder traversal.
+         */
+        PRE_ORDER,
+        /**
+         * Postorder traversal.
+         */
+        POST_ORDER
+    }
 }

kernel/src/main/java/com/itextpdf/kernel/pdf/tagutils/TagTreeIteratorAvoidDuplicatesApprover.java

@@ -0,0 +1,70 @@
+/*
+    This file is part of the iText (R) project.
+    Copyright (c) 1998-2024 Apryse Group NV
+    Authors: Apryse Software.
+
+    This program is offered under a commercial and under the AGPL license.
+    For commercial licensing, contact us at https://itextpdf.com/sales.  For AGPL licensing, see below.
+
+    AGPL licensing:
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.itextpdf.kernel.pdf.tagutils;
+
+import com.itextpdf.kernel.pdf.PdfObject;
+import com.itextpdf.kernel.pdf.tagging.IStructureNode;
+import com.itextpdf.kernel.pdf.tagging.PdfStructElem;
+import com.itextpdf.kernel.pdf.tagging.PdfStructTreeRoot;
+
+import java.util.HashSet;
+import java.util.Set;
+
+/**
+ * Element checker for {@link TagTreeIterator}.
+ * It is used to check whether specific element should be traversed.
+ * It doesn't approve elements which have been traversed before.
+ */
+public class TagTreeIteratorAvoidDuplicatesApprover extends TagTreeIteratorElementApprover {
+    private final Set<PdfObject> processedObjects = new HashSet<>();
+
+    /**
+     * Creates a new instance of {@link TagTreeIteratorAvoidDuplicatesApprover}
+     */
+    public TagTreeIteratorAvoidDuplicatesApprover() {
+        super();
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public boolean approve(IStructureNode elem) {
+        if (elem instanceof PdfStructTreeRoot) {
+            return true;
+        }
+
+        if (!super.approve(elem) || !(elem instanceof PdfStructElem)) {
+            return false;
+        }
+
+        PdfObject obj = ((PdfStructElem) elem).getPdfObject();
+        final boolean isProcessed = processedObjects.contains(obj);
+        if (isProcessed) {
+            return false;
+        } else {
+            processedObjects.add(obj);
+            return true;
+        }
+    }
+}

kernel/src/main/java/com/itextpdf/kernel/pdf/tagutils/TagTreeIteratorElementApprover.java

@@ -0,0 +1,49 @@
+/*
+    This file is part of the iText (R) project.
+    Copyright (c) 1998-2024 Apryse Group NV
+    Authors: Apryse Software.
+
+    This program is offered under a commercial and under the AGPL license.
+    For commercial licensing, contact us at https://itextpdf.com/sales.  For AGPL licensing, see below.
+
+    AGPL licensing:
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.itextpdf.kernel.pdf.tagutils;
+
+import com.itextpdf.kernel.pdf.tagging.IStructureNode;
+
+/**
+ * Element checker for {@link TagTreeIterator}.
+ * It is used to check whether specific element should be traversed.
+ */
+public class TagTreeIteratorElementApprover {
+
+    /**
+     * Creates a new instance of {@link TagTreeIteratorElementApprover}
+     */
+    public TagTreeIteratorElementApprover() {
+        // Empty constructor
+    }
+
+    /**
+     * Checks whether the element should be traversed.
+     *
+     * @param elem the element to check
+     * @return {@code true} if the element should be traversed, {@code false otherwise}
+     */
+    public boolean approve(IStructureNode elem) {
+        return elem != null;
+    }
+}

kernel/src/main/java/com/itextpdf/kernel/pdf/tagutils/TagTreeIteratorFlusher.java

@@ -0,0 +1,49 @@
+/*
+    This file is part of the iText (R) project.
+    Copyright (c) 1998-2024 Apryse Group NV
+    Authors: Apryse Software.
+
+    This program is offered under a commercial and under the AGPL license.
+    For commercial licensing, contact us at https://itextpdf.com/sales.  For AGPL licensing, see below.
+
+    AGPL licensing:
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.itextpdf.kernel.pdf.tagutils;
+
+import com.itextpdf.kernel.pdf.tagging.IStructureNode;
+import com.itextpdf.kernel.pdf.tagging.PdfStructElem;
+
+/**
+ * Class that flushes struct elements while iterating over struct tree root with {@link TagTreeIterator}.
+ */
+public class TagTreeIteratorFlusher implements ITagTreeIteratorHandler {
+
+    /**
+     * Creates a new instance of {@link TagTreeIteratorFlusher}
+     */
+    public TagTreeIteratorFlusher() {
+        // Empty constructor
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public void nextElement(IStructureNode elem) {
+        if (elem instanceof PdfStructElem && !((PdfStructElem) elem).isFlushed()) {
+            ((PdfStructElem) elem).flush();
+        }
+    }
+}