Fix PdfLayer#getIntents in case of multiple intents; add new PdfLayer tests

Also implement new comparison method of CompareTool for more local checks.

DEVSIX-3117

Author: yulian-gaponenko

kernel/src/main/java/com/itextpdf/kernel/pdf/layer/PdfLayer.java

@@ -55,8 +55,8 @@ This file is part of the iText (R) project.
 import com.itextpdf.kernel.pdf.PdfString;
 
 import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.Collection;
+import java.util.Collections;
 import java.util.List;
 
 /**
@@ -226,18 +226,25 @@ public void setOnPanel(boolean onPanel) {
 
     /**
      * Gets a collection of current intents specified for this layer.
-     * The default value is PdfName.View, so it will be the only element of the
-     * resultant colletion if no intents are currently specified.
+     * The default value is {@link PdfName#View}, so it will be the only element of the
+     * resultant collection if no intents are currently specified.
      * @return the collection of intents.
      */
     public Collection<PdfName> getIntents() {
         final PdfObject intent = getPdfObject().get(PdfName.Intent);
         if (intent instanceof PdfName)
-            return Arrays.asList((PdfName) intent);
+            return Collections.singletonList((PdfName) intent);
         else if (intent instanceof PdfArray) {
-            return (Collection<PdfName>) intent;
+            PdfArray intentArr = (PdfArray) intent;
+            Collection<PdfName> intentsCollection = new ArrayList<>(intentArr.size());
+            for (PdfObject i : intentArr) {
+                if (i instanceof PdfName) {
+                    intentsCollection.add((PdfName) i);
+                }
+            }
+            return intentsCollection;
         }
-        return Arrays.asList(PdfName.View);
+        return Collections.singletonList(PdfName.View);
     }
 
     /**
@@ -249,7 +256,7 @@ public void setIntents(List<PdfName> intents) {
             getPdfObject().remove(PdfName.Intent);
         } else if (intents.size() == 1) {
             getPdfObject().put(PdfName.Intent, intents.get(0));
-        } else if (intents.size() > 1) {
+        } else { // intents.size() > 1
             PdfArray array = new PdfArray();
             for (PdfName intent : intents) {
                 array.add(intent);

kernel/src/main/java/com/itextpdf/kernel/pdf/layer/PdfOCProperties.java

@@ -52,7 +52,6 @@ This file is part of the iText (R) project.
 import com.itextpdf.kernel.pdf.PdfObject;
 import com.itextpdf.kernel.pdf.PdfObjectWrapper;
 import com.itextpdf.kernel.pdf.PdfString;
-
 import java.util.ArrayList;
 import java.util.HashSet;
 import java.util.List;
@@ -63,38 +62,17 @@ This file is part of the iText (R) project.
 /**
  * This class represents /OCProperties entry if pdf catalog and manages
  * the layers of the pdf document.
- *
- * <br><br>
+ * <p>
  * To be able to be wrapped with this {@link PdfObjectWrapper} the {@link PdfObject}
  * must be indirect.
  */
 public class PdfOCProperties extends PdfObjectWrapper<PdfDictionary> {
 
+    static final String OC_CONFIG_NAME_PATTERN = "OCConfigName";
+
     private static final long serialVersionUID = 1137977454824741350L;
     private List<PdfLayer> layers = new ArrayList<>();
 
-    /**
-     * Gets the order of the layers in which they will be displayed in the layer view panel,
-     * including nesting.
-     */
-    private static void getOCGOrder(PdfArray order, PdfLayer layer) {
-        if (!layer.isOnPanel())
-            return;
-        if (layer.getTitle() == null)
-            order.add(layer.getPdfObject().getIndirectReference());
-        List<PdfLayer> children = layer.getChildren();
-        if (children == null)
-            return;
-        PdfArray kids = new PdfArray();
-        if (layer.getTitle() != null)
-            kids.add(new PdfString(layer.getTitle(), PdfEncodings.UNICODE_BIG));
-        for (PdfLayer child : children) {
-            getOCGOrder(kids, child);
-        }
-        if (kids.size() > 0)
-            order.add(kids);
-    }
-
     /**
      * Creates a new PdfOCProperties instance.
      *
@@ -224,24 +202,6 @@ public PdfObject fillDictionary() {
         return getPdfObject();
     }
 
-    private String createUniqueName() {
-        int uniqueID = 0;
-        Set<String> usedNames = new HashSet<>();
-        PdfArray configs = getPdfObject().getAsArray(PdfName.Configs);
-        if (null != configs) {
-            for (int i = 0; i < configs.size(); i++) {
-                PdfDictionary alternateDictionary = configs.getAsDictionary(i);
-                if (null != alternateDictionary && alternateDictionary.containsKey(PdfName.Name)) {
-                    usedNames.add(alternateDictionary.getAsString(PdfName.Name).toUnicodeString());
-                }
-            }
-        }
-        while (usedNames.contains("OCConfigName" + uniqueID)) {
-            uniqueID++;
-        }
-        return "OCConfigName" + uniqueID;
-    }
-
     @Override
     public void flush() {
         fillDictionary();
@@ -276,6 +236,28 @@ protected PdfDocument getDocument() {
         return getPdfObject().getIndirectReference().getDocument();
     }
 
+    /**
+     * Gets the order of the layers in which they will be displayed in the layer view panel,
+     * including nesting.
+     */
+    private static void getOCGOrder(PdfArray order, PdfLayer layer) {
+        if (!layer.isOnPanel())
+            return;
+        if (layer.getTitle() == null)
+            order.add(layer.getPdfObject().getIndirectReference());
+        List<PdfLayer> children = layer.getChildren();
+        if (children == null)
+            return;
+        PdfArray kids = new PdfArray();
+        if (layer.getTitle() != null)
+            kids.add(new PdfString(layer.getTitle(), PdfEncodings.UNICODE_BIG));
+        for (PdfLayer child : children) {
+            getOCGOrder(kids, child);
+        }
+        if (kids.size() > 0)
+            order.add(kids);
+    }
+
     /**
      * Populates the /AS entry in the /D dictionary.
      */
@@ -386,4 +368,22 @@ private void readOrderFromDictionary(PdfLayer parent, PdfArray orderArray, Map<P
             }
         }
     }
+
+    private String createUniqueName() {
+        int uniqueID = 0;
+        Set<String> usedNames = new HashSet<>();
+        PdfArray configs = getPdfObject().getAsArray(PdfName.Configs);
+        if (null != configs) {
+            for (int i = 0; i < configs.size(); i++) {
+                PdfDictionary alternateDictionary = configs.getAsDictionary(i);
+                if (null != alternateDictionary && alternateDictionary.containsKey(PdfName.Name)) {
+                    usedNames.add(alternateDictionary.getAsString(PdfName.Name).toUnicodeString());
+                }
+            }
+        }
+        while (usedNames.contains(OC_CONFIG_NAME_PATTERN + uniqueID)) {
+            uniqueID++;
+        }
+        return OC_CONFIG_NAME_PATTERN + uniqueID;
+    }
 }

kernel/src/main/java/com/itextpdf/kernel/utils/CompareTool.java

@@ -546,6 +546,62 @@ public boolean compareDictionaries(PdfDictionary outDict, PdfDictionary cmpDict)
         return compareDictionariesExtended(outDict, cmpDict, null, null);
     }
 
+    /**
+     * Recursively compares structures of two corresponding dictionaries from out and cmp PDF documents. You can roughly
+     * imagine it as depth-first traversal of the two trees that represent pdf objects structure of the documents.
+     * <p>
+     * Both out and cmp {@link PdfDictionary} shall have indirect references.
+     * <p>
+     * By default page dictionaries are excluded from the comparison when met and are instead compared in a special manner,
+     * simply comparing their page numbers. This behavior can be disabled by calling {@link #disableCachedPagesComparison()}.
+     * <p>
+     * For more explanations about what is outPdf and cmpPdf see last paragraph of the {@link CompareTool}
+     * class description.
+     *
+     * @param outDict an indirect {@link PdfDictionary} from the output file, which is to be compared to cmp-file dictionary.
+     * @param cmpDict an indirect {@link PdfDictionary} from the cmp-file file, which is to be compared to output file dictionary.
+     * @return {@link CompareResult} instance containing differences between the two dictionaries,
+     * or {@code null} if dictionaries are equal.
+     */
+    public CompareResult compareDictionariesStructure(PdfDictionary outDict, PdfDictionary cmpDict) {
+        return compareDictionariesStructure(outDict, cmpDict, null);
+    }
+
+    /**
+     * Recursively compares structures of two corresponding dictionaries from out and cmp PDF documents. You can roughly
+     * imagine it as depth-first traversal of the two trees that represent pdf objects structure of the documents.
+     * <p>
+     * Both out and cmp {@link PdfDictionary} shall have indirect references.
+     * <p>
+     * By default page dictionaries are excluded from the comparison when met and are instead compared in a special manner,
+     * simply comparing their page numbers. This behavior can be disabled by calling {@link #disableCachedPagesComparison()}.
+     * <p>
+     * For more explanations about what is outPdf and cmpPdf see last paragraph of the {@link CompareTool}
+     * class description.
+     *
+     * @param outDict      an indirect {@link PdfDictionary} from the output file, which is to be compared to cmp-file dictionary.
+     * @param cmpDict      an indirect {@link PdfDictionary} from the cmp-file file, which is to be compared to output file dictionary.
+     * @param excludedKeys a {@link Set} of names that designate entries from {@code outDict} and {@code cmpDict} dictionaries
+     *                     which are to be skipped during comparison.
+     * @return {@link CompareResult} instance containing differences between the two dictionaries,
+     * or {@code null} if dictionaries are equal.
+     */
+    public CompareResult compareDictionariesStructure(PdfDictionary outDict, PdfDictionary cmpDict, Set<PdfName> excludedKeys) {
+        if (outDict.getIndirectReference() == null || cmpDict.getIndirectReference() == null) {
+            throw new IllegalArgumentException("The 'outDict' and 'cmpDict' objects shall have indirect references.");
+        }
+
+        CompareResult compareResult = new CompareResult(compareByContentErrorsLimit);
+        CompareTool.ObjectPath currentPath = new ObjectPath(cmpDict.getIndirectReference(), outDict.getIndirectReference());
+        if (!compareDictionariesExtended(outDict, cmpDict, currentPath, compareResult, excludedKeys)) {
+            assert !compareResult.isOk();
+            System.out.println(compareResult.getReport());
+            return compareResult;
+        }
+        assert compareResult.isOk();
+        return null;
+    }
+
     /**
      * Simple method that compares two given PdfStreams by content. This is "deep" comparing, which means that all
      * nested objects are also compared by content.