Add javadocs and update TODO's + add a simple test

Author: guustysebie

sign/src/main/java/com/itextpdf/signatures/validation/lotl/EuropeanLotlFetcher.java

@@ -42,6 +42,11 @@ public class EuropeanLotlFetcher {
 
     private final LotlService service;
 
+    /**
+     * Constructs a new instance of {@link EuropeanLotlFetcher} with the specified LotlService.
+     *
+     * @param service the LotlService used to retrieve resources
+     */
     public EuropeanLotlFetcher(LotlService service) {
         this.service = service;
     }
@@ -86,7 +91,6 @@ public static class Result {
          */
         public Result(byte[] lotlXml) {
             setLotlXml(lotlXml);
-
         }
 
         /**

sign/src/main/java/com/itextpdf/signatures/validation/lotl/IOnCountryFetchFailureStrategy.java

@@ -26,17 +26,21 @@ This file is part of the iText (R) project.
  * Interface for handling the failure of fetching a country-specific List of Trusted Lists (Lotl).
  * Implementations can define custom strategies for dealing with such failures.
  * <p>
- * //TODO mention default implementations
+ * We provide 2 default implementations out of the box:
+ * - {@link com.itextpdf.signatures.validation.lotl.IgnoreCountrySpecificCertificates} - which does nothing and won't
+ * throw an exception, but will not add any country-specific certificates to the trust store.
+ * - {@link com.itextpdf.signatures.validation.lotl.ThrowExceptionIOnFailureStrategy} - which will throw an exception
+ * if the fetching of a country-specific Lotl fails so that the validation process can be halted.
  */
 public interface IOnCountryFetchFailureStrategy {
 
-    //TODO add javadoc for doing stuff related  certificates and validation report and their items will be added to
-    // the main report
-    //so if invalid is added main report will be invalidated
 
     /**
      * This method is called when the fetching of a country-specific Lotl fails.
      * It allows for custom handling of the failure.
+     * <p>
+     * If the implementation does not throw an exception, the validation process will continue, and the certificates
+     * from the {@code CountrySpecificLotlFetcher.Result } will not be added to the trust store.
      *
      * @param fetchResult the result of the fetch attempt, which may contain error details
      */

sign/src/main/java/com/itextpdf/signatures/validation/lotl/PivotFetcher.java

@@ -50,6 +50,12 @@ public class PivotFetcher {
     private final LotlService service;
     private final ValidatorChainBuilder builder;
 
+    /**
+     * Constructs a PivotFetcher with the specified LotlService and ValidatorChainBuilder.
+     *
+     * @param service the LotlService used to retrieve resources
+     * @param builder the ValidatorChainBuilder used to build the XML signature validator
+     */
     public PivotFetcher(LotlService service, ValidatorChainBuilder builder) {
         this.service = service;
         this.builder = builder;

sign/src/test/java/com/itextpdf/signatures/validation/lotl/InMemoryLotlServiceCacheTest.java

@@ -82,7 +82,7 @@ public void cacheInvalidationWorks() throws InterruptedException {
         byte[] data = "test data".getBytes(StandardCharsets.UTF_8);
         EuropeanLotlFetcher.Result result = new EuropeanLotlFetcher.Result(data);
         // Simulate staleness by waiting longer than the max allowed staleness
-        Thread.sleep(50);
+        Thread.sleep(250);
 
         cache.setLotlResult(result);
         assertArrayEquals(data, cache.getLotlResult().getLotlXml(), "The byte data should match the set data.");

sign/src/test/java/com/itextpdf/signatures/validation/lotl/LotlValidatorTest.java

@@ -338,6 +338,33 @@ public Result fetch() {
         });
     }
 
+
+    @Test
+    public void inMemoryCacheThrowsException() throws InterruptedException {
+        ValidatorChainBuilder chainBuilder = new ValidatorChainBuilder();
+        chainBuilder.withLotlFetchingProperties(new LotlFetchingProperties(new IgnoreCountrySpecificCertificates()));
+        chainBuilder.getLotlFetchingProperties().setCountryNames("NL");
+        chainBuilder.getLotlFetchingProperties().setCacheStalenessInMilliseconds(100);
+        chainBuilder.getLotlFetchingProperties().setRefreshIntervalCalculator((f) -> 100000);
+
+        LotlService service = new LotlService(chainBuilder);
+        service.withCustomResourceRetriever(new FromDiskResourceRetriever(SOURCE_FOLDER_LOL_FILES));
+        service.initializeCache();
+
+        chainBuilder.withLotlValidator(() -> new LotlValidator(chainBuilder).withService(service));
+
+        Thread.sleep(1000);
+
+        LotlValidator validator = chainBuilder.getLotlValidator();
+
+        Exception e = assertThrows(PdfException.class, () -> {
+            // This should throw an exception because the cache is stale
+            validator.validate();
+        });
+        Assertions.assertEquals(SignExceptionMessageConstant.STALE_DATA_IS_USED, e.getMessage());
+
+    }
+
     @Test
     @LogMessages(
             messages = {