Improve documetation for SignatureFieldAppearance#getId

DEVSIX-8163

Author: AnhelinaM

forms/src/main/java/com/itextpdf/forms/form/element/SignatureFieldAppearance.java

@@ -66,12 +66,17 @@ public class SignatureFieldAppearance extends FormField<SignatureFieldAppearance
     /**
      * Creates a new {@link SignatureFieldAppearance} instance.
      *
-     * @param id the id.
+     * @param id signature field name if you use this {@link SignatureFieldAppearance} in pure layout for the new
+     *           interactive signature field creation. ID will be ignored if this {@link SignatureFieldAppearance}
+     *           is used for signing or for existing signature field
      */
     public SignatureFieldAppearance(String id) {
-        // We should support signing of existing fields with dots in name.
+        // ID is required for the new interactive signature field creation. We can't provide parameterless constructor
+        // since the user might misuse it for unintended purpose, and we have to generate a unique field name
+        // that doesn't exist in the document acroform, which we don't have access to at this level.
         super(id != null && id.contains(".") ? "" : id);
         if (id.contains(".")) {
+            // We should support signing of existing fields with dots in name.
             idWithDots = id;
         }
         // Draw the borders inside the element by default

pdfua/src/test/java/com/itextpdf/pdfua/PdfUASignerTest.java

@@ -94,7 +94,7 @@ public void invisibleSignatureWithTU() throws GeneralSecurityException, IOExcept
         ByteArrayInputStream inPdf = generateSimplePdfUA1Document();
         String outPdf = generateSignature(inPdf, "invisibleSignatureWithTU", (signer) -> {
             signer.setSignerProperties(new SignerProperties().setFieldName("Signature12"));
-            SignatureFieldAppearance appearance = new SignatureFieldAppearance(signer.getSignerProperties().getFieldName());
+            SignatureFieldAppearance appearance = new SignatureFieldAppearance(SignerProperties.IGNORED_ID);
             appearance.getAccessibilityProperties().setAlternateDescription("Some alternate description");
             signer.getSignerProperties().setSignatureAppearance(appearance);
         });
@@ -106,7 +106,7 @@ public void visibleSignatureWithTUButNotAFont() throws GeneralSecurityException,
         ByteArrayInputStream inPdf = generateSimplePdfUA1Document();
         String outPdf = generateSignature(inPdf, "visibleSignatureWithTUButNotAFont", (signer) -> {
             signer.setSignerProperties(new SignerProperties().setFieldName("Signature12"));
-            SignatureFieldAppearance appearance = new SignatureFieldAppearance(signer.getSignerProperties().getFieldName());
+            SignatureFieldAppearance appearance = new SignatureFieldAppearance(SignerProperties.IGNORED_ID);
             appearance.getAccessibilityProperties().setAlternateDescription("Some alternate description");
             try {
                 appearance.setFont(PdfFontFactory.createFont(FONT));
@@ -128,7 +128,7 @@ public void visibleSignatureWithoutTUFont() {
         Exception e = Assertions.assertThrows(PdfUAConformanceException.class, () -> {
             generateSignature(inPdf, "visibleSignatureWithoutTUFont", (signer) -> {
                 signer.setSignerProperties(new SignerProperties().setFieldName("Signature12"));
-                SignatureFieldAppearance appearance = new SignatureFieldAppearance(signer.getSignerProperties().getFieldName());
+                SignatureFieldAppearance appearance = new SignatureFieldAppearance(SignerProperties.IGNORED_ID);
                 appearance.setContent(new SignedAppearanceText().setLocationLine("Dummy location").setReasonLine("Dummy reason").setSignedBy("Dummy"));
 
                 try {
@@ -151,7 +151,7 @@ public void visibleSignatureWithNoFontSelected() {
         Exception e = Assertions.assertThrows(PdfUAConformanceException.class, () -> {
             generateSignature(inPdf, "visibleSignatureWithNoFontSelected", (signer) -> {
                 signer.setSignerProperties(new SignerProperties().setFieldName("Signature12"));
-                SignatureFieldAppearance appearance = new SignatureFieldAppearance(signer.getSignerProperties().getFieldName());
+                SignatureFieldAppearance appearance = new SignatureFieldAppearance(SignerProperties.IGNORED_ID);
                 appearance.setContent("Some signature content");
                 signer.getSignerProperties().setPageNumber(1).setPageRect(new Rectangle(36, 648, 200, 100));
                 appearance.getAccessibilityProperties().setAlternateDescription("Some alternate description");
@@ -167,7 +167,7 @@ public void normalPdfSignerInvisibleSignatureWithTU() throws GeneralSecurityExce
         ByteArrayInputStream inPdf = generateSimplePdfUA1Document();
         String outPdf = generateSignatureNormal(inPdf, "normalPdfSignerInvisibleSignatureWithTU", (signer) -> {
             signer.setSignerProperties(new SignerProperties().setFieldName("Signature12"));
-            SignatureFieldAppearance appearance = new SignatureFieldAppearance(signer.getSignerProperties().getFieldName());
+            SignatureFieldAppearance appearance = new SignatureFieldAppearance(SignerProperties.IGNORED_ID);
             appearance.getAccessibilityProperties().setAlternateDescription("Some alternate description");
             signer.getSignerProperties().setSignatureAppearance(appearance);
         });
@@ -179,7 +179,7 @@ public void normalPdfSignerInvisibleSignatureWithoutTU() throws GeneralSecurityE
         ByteArrayInputStream inPdf = generateSimplePdfUA1Document();
         String outPdf = generateSignatureNormal(inPdf, "normalPdfSignerInvisibleSignatureWithoutTU", (signer) -> {
             signer.setSignerProperties(new SignerProperties().setFieldName("Signature12"));
-            SignatureFieldAppearance appearance = new SignatureFieldAppearance(signer.getSignerProperties().getFieldName());
+            SignatureFieldAppearance appearance = new SignatureFieldAppearance(SignerProperties.IGNORED_ID);
             signer.getSignerProperties().setSignatureAppearance(appearance);
         });
         Assertions.assertNull(new VeraPdfValidator().validate(outPdf)); // Android-Conversion-Skip-Line (TODO DEVSIX-7377 introduce pdf\a validation on Android)
@@ -192,7 +192,7 @@ public void normalPdfSignerVisibleSignatureWithoutFont() throws GeneralSecurityE
         ByteArrayInputStream inPdf = generateSimplePdfUA1Document();
         String outPdf = generateSignatureNormal(inPdf, "normalPdfSignerVisibleSignatureWithoutFont", (signer) -> {
             signer.setSignerProperties(new SignerProperties().setFieldName("Signature12"));
-            SignatureFieldAppearance appearance = new SignatureFieldAppearance(signer.getSignerProperties().getFieldName());
+            SignatureFieldAppearance appearance = new SignatureFieldAppearance(SignerProperties.IGNORED_ID);
             appearance.getAccessibilityProperties().setAlternateDescription("Some alternate description");
             appearance.setContent(new SignedAppearanceText().setLocationLine("Dummy location").setReasonLine("Dummy reason").setSignedBy("Dummy"));
             signer.getSignerProperties()
@@ -210,7 +210,7 @@ public void normalPdfSignerVisibleSignatureWithFont() throws GeneralSecurityExce
         PdfFont font = PdfFontFactory.createFont(FONT);
         String outPdf = generateSignatureNormal(inPdf, "normalPdfSignerVisibleSignatureWithFont", (signer) -> {
             signer.setSignerProperties(new SignerProperties().setFieldName("Signature12"));
-            SignatureFieldAppearance appearance = new SignatureFieldAppearance(signer.getSignerProperties().getFieldName());
+            SignatureFieldAppearance appearance = new SignatureFieldAppearance(SignerProperties.IGNORED_ID);
             appearance.getAccessibilityProperties().setAlternateDescription("Some alternate description");
             appearance.setContent(new SignedAppearanceText().setLocationLine("Dummy location").setReasonLine("Dummy reason").setSignedBy("Dummy"));
             appearance.setFont(font);
@@ -230,7 +230,7 @@ public void normalPdfSignerVisibleSignatureWithFontEmptyTU() throws GeneralSecur
         PdfFont font = PdfFontFactory.createFont(FONT);
         String outPdf = generateSignatureNormal(inPdf, "normalPdfSignerVisibleSignatureWithFontEmptyTU", (signer) -> {
             signer.setSignerProperties(new SignerProperties().setFieldName("Signature12"));
-            SignatureFieldAppearance appearance = new SignatureFieldAppearance(signer.getSignerProperties().getFieldName());
+            SignatureFieldAppearance appearance = new SignatureFieldAppearance(SignerProperties.IGNORED_ID);
             appearance.getAccessibilityProperties().setAlternateDescription("");
             appearance.setContent(new SignedAppearanceText().setLocationLine("Dummy location").setReasonLine("Dummy reason").setSignedBy("Dummy"));
             appearance.setFont(font);
@@ -250,7 +250,7 @@ public void pdfSignerVisibleSignatureWithFontEmptyTU() throws IOException {
         Assertions.assertThrows(PdfUAConformanceException.class, () -> {
             generateSignature(inPdf, "pdfSignerVisibleSignatureWithFontEmptyTU", (signer) -> {
                 signer.setSignerProperties(new SignerProperties().setFieldName("Signature12"));
-                SignatureFieldAppearance appearance = new SignatureFieldAppearance(signer.getSignerProperties().getFieldName());
+                SignatureFieldAppearance appearance = new SignatureFieldAppearance(SignerProperties.IGNORED_ID);
                 appearance.getAccessibilityProperties().setAlternateDescription("");
                 appearance.setContent(new SignedAppearanceText().setLocationLine("Dummy location").setReasonLine("Dummy reason").setSignedBy("Dummy"));
                 appearance.setFont(font);

sign/src/main/java/com/itextpdf/signatures/PdfSigner.java

@@ -995,8 +995,7 @@ protected void preClose(Map<PdfName, Integer> exclusionSizes) throws IOException
      */
     protected SignatureFieldAppearance getSignatureAppearance() {
         if (this.signerProperties.getSignatureAppearance() == null) {
-            this.signerProperties.setSignatureAppearance(
-                    new SignatureFieldAppearance(this.signerProperties.getFieldName()));
+            this.signerProperties.setSignatureAppearance(new SignatureFieldAppearance(SignerProperties.IGNORED_ID));
             setContent();
         } else {
             populateExistingModelElement();

sign/src/main/java/com/itextpdf/signatures/SignerProperties.java

@@ -35,6 +35,7 @@ This file is part of the iText (R) project.
  * Properties to be used in signing operations.
  */
 public class SignerProperties {
+    public static final String IGNORED_ID = "";
 
     private PdfSigFieldLock fieldLock;
     private SignatureFieldAppearance appearance;
@@ -78,6 +79,8 @@ public SignerProperties setClaimedSignDate(java.util.Calendar signDate) {
 
     /**
      * Sets the signature field layout element to customize the appearance of the signature.
+     * ID specified for {@link SignatureFieldAppearance} will be ignored and won't override field name, so
+     * {@link #IGNORED_ID} could be used. To specify signature name use {@link SignerProperties#setFieldName}.
      *
      * <p>
      * Note that if {@link SignedAppearanceText} was set as the content (or part of the content)
@@ -154,6 +157,10 @@ public String getFieldName() {
      * Sets the name indicating the field to be signed. The field can already be presented in the
      * document but shall not be signed. If the field is not presented in the document, it will be created.
      *
+     * <p>
+     * Note that ID specified for {@link SignatureFieldAppearance} set by {@link #setSignatureAppearance} will be
+     * ignored and won't override the field name.
+     *
      * @param fieldName the name indicating the field to be signed
      *
      * @return this instance to support fluent interface

sign/src/test/java/com/itextpdf/signatures/PdfSignerUnitTest.java

@@ -287,7 +287,7 @@ public void setAlternativeName() throws IOException, GeneralSecurityException {
                 .setPageRect(new Rectangle(100, 100, 10, 10));
         signer.setSignerProperties(signerProperties);
 
-        SignatureFieldAppearance appearance = new SignatureFieldAppearance(signerProperties.getFieldName());
+        SignatureFieldAppearance appearance = new SignatureFieldAppearance(SignerProperties.IGNORED_ID);
         appearance.setContent("Some text");
         appearance.getAccessibilityProperties().setAlternateDescription("Alternate description");
         signerProperties.setSignatureAppearance(appearance);

sign/src/test/java/com/itextpdf/signatures/sign/AnnotationsSigningTest.java

@@ -184,7 +184,7 @@ protected void sign(String src, String name, String dest,
                 .setFieldName(name);
 
         // Creating the appearance
-        SignatureFieldAppearance appearance = new SignatureFieldAppearance(name)
+        SignatureFieldAppearance appearance = new SignatureFieldAppearance(SignerProperties.IGNORED_ID)
                 .setContent(new SignedAppearanceText());
         signerProperties
                 .setReason(reason)

sign/src/test/java/com/itextpdf/signatures/sign/IsoSignatureExtensionsRoundtripTest.java

@@ -312,7 +312,7 @@ private void doSign(String keySampleName, String digestAlgo, String signatureAlg
         IExternalSignature pks = new PrivateKeySignature(signPrivateKey, digestAlgo, signatureAlgo, BOUNCY_CASTLE_FACTORY.getProviderName(), null);
 
         PdfSigner signer = new PdfSigner(new PdfReader(SOURCE_FILE), os, new StampingProperties());
-        SignatureFieldAppearance appearance = new SignatureFieldAppearance(SIGNATURE_FIELD)
+        SignatureFieldAppearance appearance = new SignatureFieldAppearance(SignerProperties.IGNORED_ID)
                 .setContent("Approval test signature.\nCreated by iText.");
         SignerProperties signerProperties = new SignerProperties()
                 .setFieldName(SIGNATURE_FIELD)

sign/src/test/java/com/itextpdf/signatures/sign/PadesSigTest.java

@@ -182,7 +182,7 @@ private void signApproval(String signCertFileName, String outFileName,
                 new StampingProperties());
         SignerProperties signerProperties = new SignerProperties().setFieldName("Signature1");
         signer.setSignerProperties(signerProperties);
-        SignatureFieldAppearance appearance = new SignatureFieldAppearance(signer.getSignerProperties().getFieldName())
+        SignatureFieldAppearance appearance = new SignatureFieldAppearance(SignerProperties.IGNORED_ID)
                 .setContent("Approval test signature.\nCreated by iText.");
         signerProperties
                 .setPageRect(new Rectangle(50, 650, 200, 100))

sign/src/test/java/com/itextpdf/signatures/sign/PadesSignatureLevelTest.java

@@ -95,7 +95,7 @@ public void padesSignatureLevelTTest01()
         PrivateKey tsaPrivateKey = PemFileHelper.readFirstKey(tsaCertFileName, password);
 
         PdfSigner signer = new PdfSigner(new PdfReader(srcFileName), FileUtil.getFileOutputStream(outFileName), new StampingProperties());
-        SignatureFieldAppearance appearance = new SignatureFieldAppearance("Signature1")
+        SignatureFieldAppearance appearance = new SignatureFieldAppearance(SignerProperties.IGNORED_ID)
                 .setContent("Approval test signature.\nCreated by iText.");
         SignerProperties signerProperties = new SignerProperties()
                 .setFieldName("Signature1")

sign/src/test/java/com/itextpdf/signatures/sign/PadesTwoPhaseSigningLevelsTest.java

@@ -315,7 +315,7 @@ public void twoStepSigningBaselineLTATest(Boolean useTempFolder, String digestAl
     private SignerProperties createSignerProperties() {
         SignerProperties signerProperties = new SignerProperties();
         signerProperties.setFieldName("Signature1");
-        SignatureFieldAppearance appearance = new SignatureFieldAppearance(signerProperties.getFieldName())
+        SignatureFieldAppearance appearance = new SignatureFieldAppearance(SignerProperties.IGNORED_ID)
                 .setContent("Approval test signature.\nCreated by iText.");
         signerProperties.setPageRect(new Rectangle(50, 650, 200, 100))
                 .setSignatureAppearance(appearance);