DSS engine: add background image layering, text auto-scaling, and tolerant field placement

engines/dss/src/main/java/net/sf/jsignpdf/engine/dss/DssSigningEngine.java

@@ -53,9 +53,12 @@
 import org.apache.pdfbox.pdmodel.PDPage;
 import org.apache.pdfbox.pdmodel.common.PDRectangle;
 
+import eu.europa.esig.dss.alert.LogOnStatusAlert;
 import eu.europa.esig.dss.enumerations.CertificationPermission;
 import eu.europa.esig.dss.enumerations.DigestAlgorithm;
 import eu.europa.esig.dss.enumerations.SignatureLevel;
+import eu.europa.esig.dss.enumerations.TextWrapping;
+import eu.europa.esig.dss.pdf.PdfSignatureFieldPositionChecker;
 import eu.europa.esig.dss.model.DSSDocument;
 import eu.europa.esig.dss.model.FileDocument;
 import eu.europa.esig.dss.model.SignatureValue;
@@ -64,6 +67,8 @@
 import eu.europa.esig.dss.pades.PAdESSignatureParameters;
 import eu.europa.esig.dss.pades.SignatureFieldParameters;
 import eu.europa.esig.dss.pades.SignatureImageParameters;
+import net.sf.jsignpdf.engine.dss.pdfbox.JSignPdfPdfObjFactory;
+import net.sf.jsignpdf.engine.dss.pdfbox.JSignPdfSignatureImageParameters;
 import eu.europa.esig.dss.pades.SignatureImageTextParameters;
 import eu.europa.esig.dss.pades.signature.PAdESService;
 import eu.europa.esig.dss.service.http.commons.TimestampDataLoader;
@@ -300,6 +305,14 @@ public boolean sign(final BasicSignerOptions options, final EngineConfig engineC
                 }
                 final PAdESService service = new PAdESService(verifier);
 
+                // Use custom PDF object factory with background-image layering
+                // and tolerant signature field position checking
+                JSignPdfPdfObjFactory pdfObjFactory = new JSignPdfPdfObjFactory();
+                PdfSignatureFieldPositionChecker positionChecker = new PdfSignatureFieldPositionChecker();
+                positionChecker.setAlertOnSignatureFieldOverlap(new LogOnStatusAlert());
+                pdfObjFactory.setPdfSignatureFieldPositionChecker(positionChecker);
+                service.setPdfObjFactory(pdfObjFactory);
+
                 if (useTsa) {
                     LOGGER.info(RES.get("console.creatingTsaClient"));
                     service.setTspSource(buildTspSource(options, parameters, digestAlgorithm, proxyConfig));
@@ -551,7 +564,7 @@ private AccessPermission buildAccessPermission(BasicSignerOptions options) {
 
     private void configureVisibleSignature(PAdESSignatureParameters parameters, BasicSignerOptions options,
             Certificate[] chain, Calendar signingCal, File inFile) throws Exception {
-        final SignatureImageParameters imageParams = new SignatureImageParameters();
+        final JSignPdfSignatureImageParameters imageParams = new JSignPdfSignatureImageParameters();
 
         int page = options.getPage();
         float pageWidth;
@@ -590,19 +603,34 @@ private void configureVisibleSignature(PAdESSignatureParameters parameters, Basi
         final RenderMode renderMode = options.getRenderMode();
         final boolean withGraphic = renderMode == RenderMode.GRAPHIC_AND_DESCRIPTION;
 
-        // DSS renders a single signature image. In GRAPHIC_AND_DESCRIPTION mode that image is the signature
-        // graphic (options.imgPath); in the other render modes it is the background image (options.bgImgPath).
-        // The two are mutually exclusive here (unlike OpenPDF, which layers them), and we never silently
-        // substitute one for the other: a graphic render mode with no graphic configured yields text only.
-        final String imagePath = withGraphic ? options.getImgPath() : options.getBgImgPath();
-        if (imagePath != null) {
-            LOGGER.info(RES.get("console.createImage", imagePath));
-            imageParams.setImage(new FileDocument(imagePath));
+        // Background image (drawn first, behind everything) — available in all modes
+        final String bgImgPath = options.getBgImgPath();
+        if (bgImgPath != null) {
+            LOGGER.info(RES.get("console.createImage", bgImgPath));
+            imageParams.setBackgroundImage(new FileDocument(bgImgPath));
+            imageParams.setBackgroundScale(options.getBgImgScale());
+        }
+
+        // Foreground signature graphic (drawn above background, below text) — used in GRAPHIC_AND_DESCRIPTION mode
+        if (withGraphic) {
+            final String imgPath = options.getImgPath();
+            if (imgPath != null) {
+                LOGGER.info(RES.get("console.createImage", imgPath));
+                imageParams.setImage(new FileDocument(imgPath));
+            }
         }
 
         LOGGER.info(RES.get("console.setL2Text"));
         final SignatureImageTextParameters textParams = new SignatureImageTextParameters();
         textParams.setText(buildSignatureText(options, chain, signingCal));
+        // FILL_BOX_AND_LINEBREAK: DSS auto-calculates the largest font that fits
+        // the signature rectangle, wrapping lines as needed. The font-size field
+        // in the GUI is used as the starting reference but the actual size is
+        // driven entirely by the box dimensions in this mode.
+        textParams.setTextWrapping(TextWrapping.FILL_BOX_AND_LINEBREAK);
+        // Transparent text background so the background image shows through.
+        // (DSS defaults to solid white which would paint over the image.)
+        textParams.setBackgroundColor(null);
         final DSSFont font = DssFontUtils.getVisibleSignatureFont();
         if (font != null) {
             float fontSize = options.getL2TextFontSize();