Refactor getters and setters in annotation package

Deprecate all getters and setters that don't belong to all
subclasses and add respective methods to subclasses that actually
support them, move common logic to util classes.

DEVSIX-1401

Author: IdamkinI

kernel/src/main/java/com/itextpdf/kernel/pdf/annot/BorderStyleUtil.java

@@ -0,0 +1,51 @@
+package com.itextpdf.kernel.pdf.annot;
+
+import com.itextpdf.kernel.pdf.PdfArray;
+import com.itextpdf.kernel.pdf.PdfDictionary;
+import com.itextpdf.kernel.pdf.PdfName;
+
+class BorderStyleUtil {
+
+    private BorderStyleUtil(){
+    }
+
+    /**
+     * Setter for the border style. Possible values are
+     * <ul>
+     *     <li>{@link PdfAnnotation#STYLE_SOLID} - A solid rectangle surrounding the annotation.</li>
+     *     <li>{@link PdfAnnotation#STYLE_DASHED} - A dashed rectangle surrounding the annotation.</li>
+     *     <li>{@link PdfAnnotation#STYLE_BEVELED} - A simulated embossed rectangle that appears to be raised above the surface of the page.</li>
+     *     <li>{@link PdfAnnotation#STYLE_INSET} - A simulated engraved rectangle that appears to be recessed below the surface of the page.</li>
+     *     <li>{@link PdfAnnotation#STYLE_UNDERLINE} - A single line along the bottom of the annotation rectangle.</li>
+     * </ul>
+     * See also ISO-320001, Table 166.
+     * @param bs original border style dictionary.
+     * @param style The new value for the annotation's border style.
+     * @return Updated border style dictionary entry.
+     */
+    public static final PdfDictionary setStyle(PdfDictionary bs, PdfName style) {
+        if (null == bs) {
+            bs = new PdfDictionary();
+        }
+        bs.put(PdfName.S, style);
+        return bs;
+    }
+
+    /**
+     * Setter for the dashed border style. This property has affect only if {@link PdfAnnotation#STYLE_DASHED}
+     * style was used for border style (see {@link #setStyle(PdfDictionary, PdfName)}.
+     * See ISO-320001 8.4.3.6, “Line Dash Pattern” for the format in which dash pattern shall be specified.
+     *
+     * @param bs original border style dictionary.
+     * @param dashPattern a dash array defining a pattern of dashes and gaps that
+     *                    shall be used in drawing a dashed border.
+     * @return Updated border style dictionary entry.
+     */
+    public static final PdfDictionary setDashPattern(PdfDictionary bs, PdfArray dashPattern) {
+        if (null == bs) {
+            bs = new PdfDictionary();
+        }
+        bs.put(PdfName.D, dashPattern);
+        return bs;
+    }
+}

kernel/src/main/java/com/itextpdf/kernel/pdf/annot/InteriorColorUtil.java

@@ -0,0 +1,38 @@
+package com.itextpdf.kernel.pdf.annot;
+
+import com.itextpdf.kernel.color.Color;
+import com.itextpdf.kernel.color.DeviceCmyk;
+import com.itextpdf.kernel.color.DeviceGray;
+import com.itextpdf.kernel.color.DeviceRgb;
+import com.itextpdf.kernel.pdf.PdfArray;
+import com.itextpdf.kernel.pdf.PdfName;
+
+class InteriorColorUtil {
+
+    private InteriorColorUtil() {
+    }
+
+    /**
+     * The interior color which is used to fill areas specific for different types of annotation. For {@link PdfLineAnnotation}
+     * and polyline annotation ({@link PdfPolyGeomAnnotation} - the annotation's line endings, for {@link PdfSquareAnnotation}
+     * and {@link PdfCircleAnnotation} - the annotation's rectangle or ellipse, for {@link PdfRedactAnnotation} - the redacted
+     * region after the affected content has been removed.
+     * @return {@link Color} of either {@link DeviceGray}, {@link DeviceRgb} or {@link DeviceCmyk} type which defines
+     * interior color of the annotation, or null if interior color is not specified.
+     */
+    public static Color parseInteriorColor(PdfArray color) {
+        if (color == null) {
+            return null;
+        }
+        switch (color.size()) {
+            case 1:
+                return new DeviceGray(color.getAsNumber(0).floatValue());
+            case 3:
+                return new DeviceRgb(color.getAsNumber(0).floatValue(), color.getAsNumber(1).floatValue(), color.getAsNumber(2).floatValue());
+            case 4:
+                return new DeviceCmyk(color.getAsNumber(0).floatValue(), color.getAsNumber(1).floatValue(), color.getAsNumber(2).floatValue(), color.getAsNumber(3).floatValue());
+            default:
+                return null;
+        }
+    }
+}

kernel/src/main/java/com/itextpdf/kernel/pdf/annot/PdfAnnotation.java

@@ -162,31 +162,31 @@ public abstract class PdfAnnotation extends PdfObjectWrapper<PdfDictionary> {
 
     /**
      * Annotation border style. See ISO-320001, Table 166 (S key).
-     * Also see {@link PdfAnnotation#setBorderStyle(PdfName)}
+     * Also see {@link BorderStyleUtil#setStyle(PdfDictionary, PdfName)}
      */
     public static final PdfName STYLE_SOLID = PdfName.S;
 
     /**
      * Annotation border style. See ISO-320001, Table 166 (S key).
-     * Also see {@link PdfAnnotation#setBorderStyle(PdfName)}
+     * Also see {@link BorderStyleUtil#setStyle(PdfDictionary, PdfName)}
      */
     public static final PdfName STYLE_DASHED = PdfName.D;
 
     /**
      * Annotation border style. See ISO-320001, Table 166 (S key).
-     * Also see {@link PdfAnnotation#setBorderStyle(PdfName)}
+     * Also see {@link BorderStyleUtil#setStyle(PdfDictionary, PdfName)}
      */
     public static final PdfName STYLE_BEVELED = PdfName.B;
 
     /**
      * Annotation border style. See ISO-320001, Table 166 (S key).
-     * Also see {@link PdfAnnotation#setBorderStyle(PdfName)}
+     * Also see {@link BorderStyleUtil#setStyle(PdfDictionary, PdfName)}
      */
     public static final PdfName STYLE_INSET = PdfName.I;
 
     /**
      * Annotation border style. See ISO-320001, Table 166 (S key).
-     * Also see {@link PdfAnnotation#setBorderStyle(PdfName)}
+     * Also see {@link BorderStyleUtil#setStyle(PdfDictionary, PdfName)}
      */
     public static final PdfName STYLE_UNDERLINE = PdfName.U;
 
@@ -364,6 +364,7 @@ public void setLayer(IPdfOCG layer) {
      * @param action {@link PdfAction} to set to this annotation.
      * @return this {@link PdfAnnotation} instance.
      */
+    @Deprecated
     public PdfAnnotation setAction(PdfAction action) {
         return put(PdfName.A, action.getPdfObject());
     }
@@ -375,6 +376,7 @@ public PdfAnnotation setAction(PdfAction action) {
      * @param action {@link PdfAction} to set as additional to this annotation.
      * @return this {@link PdfAnnotation} instance.
      */
+    @Deprecated
     public PdfAnnotation setAdditionalAction(PdfName key, PdfAction action) {
         PdfAction.setAdditionalAction(this, key, action);
         return this;
@@ -891,6 +893,7 @@ public PdfAnnotation setStructParentIndex(int structParentIndex) {
      * This flag has affect to not all kinds of annotations.
      * @return true if annotation is initially open, false - if closed.
      */
+    @Deprecated
     public boolean getOpen() {
         PdfBoolean open = getPdfObject().getAsBoolean(PdfName.Open);
         return open != null && open.getValue();
@@ -902,6 +905,7 @@ public boolean getOpen() {
      * @param open true if annotation shall initially be open, false - if closed.
      * @return this {@link PdfAnnotation} instance.
      */
+    @Deprecated
     public PdfAnnotation setOpen(boolean open) {
         return put(PdfName.Open, PdfBoolean.valueOf(open));
     }
@@ -925,6 +929,7 @@ public PdfAnnotation setOpen(boolean open) {
      * just as Acrobat and probably most other viewers expect.
      * @return an {@link PdfArray} of 8 × n numbers specifying the coordinates of n quadrilaterals.
      */
+    @Deprecated
     public PdfArray getQuadPoints() {
         return getPdfObject().getAsArray(PdfName.QuadPoints);
     }
@@ -944,6 +949,7 @@ public PdfArray getQuadPoints() {
      * @param quadPoints an {@link PdfArray} of 8 × n numbers specifying the coordinates of n quadrilaterals.
      * @return this {@link PdfAnnotation} instance.
      */
+    @Deprecated
     public PdfAnnotation setQuadPoints(PdfArray quadPoints) {
         return put(PdfName.QuadPoints, quadPoints);
     }
@@ -955,6 +961,7 @@ public PdfAnnotation setQuadPoints(PdfArray quadPoints) {
      *                    in drawing the annotation’s border.
      * @return this {@link PdfAnnotation} instance.
      */
+    @Deprecated
     public PdfAnnotation setBorderStyle(PdfDictionary borderStyle) {
         return put(PdfName.BS, borderStyle);
     }
@@ -973,13 +980,9 @@ public PdfAnnotation setBorderStyle(PdfDictionary borderStyle) {
      * @return The annotation which this method was called on.
      * @see PdfAnnotation#getBorderStyle()
      */
+    @Deprecated
     public PdfAnnotation setBorderStyle(PdfName style) {
-        PdfDictionary styleDict = getBorderStyle();
-        if (null == styleDict) {
-            styleDict = new PdfDictionary();
-        }
-        styleDict.put(PdfName.S, style);
-        return setBorderStyle(styleDict);
+        return setBorderStyle(BorderStyleUtil.setStyle(getBorderStyle(), style));
     }
 
     /**
@@ -990,13 +993,9 @@ public PdfAnnotation setBorderStyle(PdfName style) {
      *                    shall be used in drawing a dashed border.
      * @return this {@link PdfAnnotation} instance.
      */
+    @Deprecated
     public PdfAnnotation setDashPattern(PdfArray dashPattern) {
-        PdfDictionary styleDict = getBorderStyle();
-        if (null == styleDict) {
-            styleDict = new PdfDictionary();
-        }
-        styleDict.put(PdfName.D, dashPattern);
-        return setBorderStyle(styleDict);
+        return setBorderStyle(BorderStyleUtil.setDashPattern(getBorderStyle(), dashPattern));
     }
 
     /**
@@ -1007,6 +1006,7 @@ public PdfAnnotation setDashPattern(PdfArray dashPattern) {
      * precedence over the BS entry. For more info on BS entry see ISO-320001, Table 166.
      * @return {@link PdfDictionary} which is a border style dictionary or null if it is not specified.
      */
+    @Deprecated
     public PdfDictionary getBorderStyle() {
         return getPdfObject().getAsDictionary(PdfName.BS);
     }
@@ -1037,6 +1037,7 @@ public PdfString getTitle() {
      * @param characteristics the {@link PdfDictionary} with additional information for appearance stream.
      * @return this {@link PdfAnnotation} instance.
      */
+    @Deprecated
     public PdfAnnotation setAppearanceCharacteristics(PdfDictionary characteristics) {
         return put(PdfName.MK, characteristics);
     }
@@ -1047,6 +1048,7 @@ public PdfAnnotation setAppearanceCharacteristics(PdfDictionary characteristics)
      * This property affects {@link PdfWidgetAnnotation} and {@link PdfScreenAnnotation}.
      * @return an appearance characteristics dictionary or null if it isn't specified.
      */
+    @Deprecated
     public PdfDictionary getAppearanceCharacteristics() {
         return getPdfObject().getAsDictionary(PdfName.MK);
     }
@@ -1056,6 +1058,7 @@ public PdfDictionary getAppearanceCharacteristics() {
      * changing an annotation’s appearance state etc, when the annotation is activated.
      * @return {@link PdfDictionary} which defines the characteristics and behaviour of an action.
      */
+    @Deprecated
     public PdfDictionary getAction() {
         return getPdfObject().getAsDictionary(PdfName.A);
     }
@@ -1066,6 +1069,7 @@ public PdfDictionary getAction() {
      * @return an additional actions {@link PdfDictionary}.
      * @see PdfAnnotation#getAction()
      */
+    @Deprecated
     public PdfDictionary getAdditionalAction() {
         return getPdfObject().getAsDictionary(PdfName.AA);
     }

kernel/src/main/java/com/itextpdf/kernel/pdf/annot/PdfCaretAnnotation.java

@@ -44,6 +44,7 @@ This file is part of the iText (R) project.
 package com.itextpdf.kernel.pdf.annot;
 
 import com.itextpdf.kernel.geom.Rectangle;
+import com.itextpdf.kernel.pdf.PdfArray;
 import com.itextpdf.kernel.pdf.PdfDictionary;
 import com.itextpdf.kernel.pdf.PdfName;
 import com.itextpdf.kernel.pdf.PdfString;
@@ -72,4 +73,31 @@ public PdfCaretAnnotation setSymbol(PdfString symbol) {
     public PdfString getSymbol() {
         return getPdfObject().getAsString(PdfName.Sy);
     }
+
+    /**
+     * A set of four numbers describing the numerical differences between two rectangles:
+     * the Rect entry of the annotation and the actual boundaries of the underlying caret.
+     *
+     * @return null if not specified, otherwise a {@link PdfArray} with four numbers which correspond to the
+     * differences in default user space between the left, top, right, and bottom coordinates of Rect and those
+     * of the inner rectangle, respectively.
+     */
+    public PdfArray getRectangleDifferences() {
+        return getPdfObject().getAsArray(PdfName.RD);
+    }
+
+    /**
+     * A set of four numbers describing the numerical differences between two rectangles:
+     * the Rect entry of the annotation and the actual boundaries of the underlying caret.
+     *
+     * @param rect a {@link PdfArray} with four numbers which correspond to the differences in default user space between
+     *             the left, top, right, and bottom coordinates of Rect and those of the inner rectangle, respectively.
+     *             Each value shall be greater than or equal to 0. The sum of the top and bottom differences shall be
+     *             less than the height of Rect, and the sum of the left and right differences shall be less than
+     *             the width of Rect.
+     * @return this {@link PdfCaretAnnotation} instance.
+     */
+    public PdfCaretAnnotation setRectangleDifferences(PdfArray rect) {
+        return (PdfCaretAnnotation) put(PdfName.RD, rect);
+    }
 }