Add caching to LOTL mechanism + finalize api

DEVSIX-9263

Author: guustysebie

commons/src/main/java/com/itextpdf/commons/utils/MultiThreadingUtil.java

@@ -0,0 +1,78 @@
+/*
+    This file is part of the iText (R) project.
+    Copyright (c) 1998-2025 Apryse Group NV
+    Authors: Apryse Software.
+
+    This program is offered under a commercial and under the AGPL license.
+    For commercial licensing, contact us at https://itextpdf.com/sales.  For AGPL licensing, see below.
+
+    AGPL licensing:
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.itextpdf.commons.utils;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.Callable;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+
+/**
+ * Utility class for running actions in parallel using multiple threads.
+ * This class provides a method to execute a list of Callable actions in parallel
+ * and collect their results.
+ */
+public class MultiThreadingUtil {
+
+    private MultiThreadingUtil() {
+        // Private constructor to prevent instantiation
+    }
+
+    /**
+     * Runs a list of Callable actions in parallel using a fixed thread pool.
+     *
+     * @param actions         the list of Callable actions to be executed
+     * @param numberOfThreads the number of threads to use for parallel execution
+     * @param <T>             the type of the result returned by the Callable actions
+     *
+     * @return a list of results from the executed actions
+     */
+    public static <T> List<T> runActionsParallel(List<Callable<T>> actions, int numberOfThreads) {
+        final int amountOfThreads = Math.max(
+                Math.min(numberOfThreads, Runtime.getRuntime().availableProcessors()), 1);
+        ExecutorService service = Executors.newFixedThreadPool(amountOfThreads);
+        try {
+            List<T> results = new ArrayList<>();
+            List<Future<T>> f = service.invokeAll(actions);
+            for (Future<T> tFuture : f) {
+                try {
+                    T future = tFuture.get();
+                    if (future != null) {
+                        results.add(future);
+                    }
+                } catch (Exception e) {
+                    throw new RuntimeException("Error while executing action in parallel", e);
+                }
+            }
+            return results;
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new RuntimeException("Thread was interrupted while executing actions in parallel", e);
+        } finally {
+            service.shutdown();
+        }
+    }
+
+}

commons/src/main/java/com/itextpdf/commons/utils/SystemUtil.java

@@ -41,6 +41,10 @@ public final class SystemUtil {
 
     private final static String SPLIT_REGEX = "((\".+?\"|[^'\\s]|'.+?')+)\\s*";
 
+    private SystemUtil() {
+        // Empty constructor.
+    }
+
     /**
      * Gets seed as long value of current time in milliseconds.
      *
@@ -59,10 +63,6 @@ public static int getTimeBasedIntSeed() {
         return (int) System.currentTimeMillis();
     }
 
-    private SystemUtil() {
-        // Empty constructor.
-    }
-
     /**
      * Should be used in relative constructs (for example to check how many milliseconds have passed).
      *
@@ -75,6 +75,15 @@ public static long getRelativeTimeMillis() {
         return System.currentTimeMillis();
     }
 
+    /**
+     * Gets current time in milliseconds since the epoch (January 1, 1970, 00:00:00 GMT).
+     *
+     * @return current time in milliseconds.
+     */
+    public static long currentTimeMillis() {
+        return System.currentTimeMillis();
+    }
+
     /**
      * Gets free available memory for JDK.
      *
@@ -88,6 +97,7 @@ public static long getFreeMemory() {
      * Gets either java property or environment variable with given name.
      *
      * @param name the name of either java property or environment variable.
+     *
      * @return property or variable value or null if there is no such.
      */
     public static String getPropertyOrEnvironmentVariable(String name) {
@@ -99,88 +109,96 @@ public static String getPropertyOrEnvironmentVariable(String name) {
     }
 
     /**
-     * Executes the specified command and arguments in a separate process with the specified environment and working directory.
+     * Executes the specified command and arguments in a separate process with the specified environment and working
+     * directory.
      * This method checks that exec is a valid operating system command. Which commands are valid is system-dependent,
      * but at the very least the command must be a non-empty and non-null.
      * The subprocess inherits the environment settings of the current process.
-     * A minimal set of system dependent environment variables may be required to start a process on some operating systems.
+     * A minimal set of system dependent environment variables may be required to start a process on some operating
+     * systems.
      * The working directory of the new subprocess is the current working directory of the current process.
      *
-     * @param exec a specified system command.
+     * @param exec   a specified system command.
      * @param params a parameters for the specifed system command.
      *
      * @return true if subprocess was successfully executed, false otherwise.
      *
-     * @throws IOException if any I/O error occurs.
+     * @throws IOException          if any I/O error occurs.
      * @throws InterruptedException if process was interrupted.
      */
     public static boolean runProcessAndWait(String exec, String params) throws IOException, InterruptedException {
         return runProcessAndWait(exec, params, null);
     }
 
     /**
-     * Executes the specified command and arguments in a separate process with the specified environment and working directory.
+     * Executes the specified command and arguments in a separate process with the specified environment and working
+     * directory.
      * This method checks that exec is a valid operating system command. Which commands are valid is system-dependent,
      * but at the very least the command must be a non-empty and non-null.
      * The subprocess inherits the environment settings of the current process.
-     * A minimal set of system dependent environment variables may be required to start a process on some operating systems.
+     * A minimal set of system dependent environment variables may be required to start a process on some operating
+     * systems.
      * The working directory of the new subprocess is specified by workingDirPath.
      * If dir is null, the subprocess inherits the current working directory of the current process.
      *
-     * @param exec a specified system command.
-     * @param params a parameters for the specifed system command.
+     * @param exec           a specified system command.
+     * @param params         a parameters for the specifed system command.
      * @param workingDirPath working dir for subprocess.
      *
      * @return true if subprocess was successfully executed, false otherwise.
      *
-     * @throws IOException if any I/O error occurs.
+     * @throws IOException          if any I/O error occurs.
      * @throws InterruptedException if process was interrupted.
      */
     public static boolean runProcessAndWait(String exec, String params,
-                                            String workingDirPath) throws IOException, InterruptedException {
+            String workingDirPath) throws IOException, InterruptedException {
         return runProcessAndGetExitCode(exec, params, workingDirPath) == 0;
     }
 
     /**
-     * Executes the specified command and arguments in a separate process with the specified environment and working directory.
+     * Executes the specified command and arguments in a separate process with the specified environment and working
+     * directory.
      * This method checks that exec is a valid operating system command. Which commands are valid is system-dependent,
      * but at the very least the command must be a non-empty and non-null.
      * The subprocess inherits the environment settings of the current process.
-     * A minimal set of system dependent environment variables may be required to start a process on some operating systems.
+     * A minimal set of system dependent environment variables may be required to start a process on some operating
+     * systems.
      * The working directory of the new subprocess is the current working directory of the current process.
      *
-     * @param exec a specified system command.
+     * @param exec   a specified system command.
      * @param params a parameters for the specifed system command.
      *
      * @return exit code.
      *
-     * @throws IOException if any I/O error occurs.
+     * @throws IOException          if any I/O error occurs.
      * @throws InterruptedException if process was interrupted.
      */
     public static int runProcessAndGetExitCode(String exec, String params) throws IOException, InterruptedException {
         return runProcessAndGetExitCode(exec, params, null);
     }
 
     /**
-     * Executes the specified command and arguments in a separate process with the specified environment and working directory.
+     * Executes the specified command and arguments in a separate process with the specified environment and working
+     * directory.
      * This method checks that exec is a valid operating system command. Which commands are valid is system-dependent,
      * but at the very least the command must be a non-empty and non-null.
      * The subprocess inherits the environment settings of the current process.
-     * A minimal set of system dependent environment variables may be required to start a process on some operating systems.
+     * A minimal set of system dependent environment variables may be required to start a process on some operating
+     * systems.
      * The working directory of the new subprocess is specified by workingDirPath.
      * If dir is null, the subprocess inherits the current working directory of the current process.
      *
-     * @param exec a specified system command.
-     * @param params a parameters for the specifed system command.
+     * @param exec           a specified system command.
+     * @param params         a parameters for the specifed system command.
      * @param workingDirPath working dir for subprocess.
      *
      * @return exit code.
      *
-     * @throws IOException if any I/O error occurs.
+     * @throws IOException          if any I/O error occurs.
      * @throws InterruptedException if process was interrupted.
      */
     public static int runProcessAndGetExitCode(String exec, String params,
-                                               String workingDirPath) throws IOException, InterruptedException {
+            String workingDirPath) throws IOException, InterruptedException {
         Process p = runProcess(exec, params, workingDirPath);
         System.out.println(getProcessOutput(p));
         return p.waitFor();
@@ -192,12 +210,13 @@ public static int runProcessAndGetExitCode(String exec, String params,
      * This method checks that exec is a valid operating system command. Which commands are valid is system-dependent,
      * but at the very least the command must be a non-empty and non-null.
      * The subprocess inherits the environment settings of the current process.
-     * A minimal set of system dependent environment variables may be required to start a process on some operating systems.
+     * A minimal set of system dependent environment variables may be required to start a process on some operating
+     * systems.
      * The working directory of the new subprocess is specified by workingDirPath.
      * If dir is null, the subprocess inherits the current working directory of the current process.
      *
      * @param command a specified system command.
-     * @param params a parameters for the specifed system command.
+     * @param params  a parameters for the specifed system command.
      *
      * @return subprocess output result.
      *
@@ -213,12 +232,13 @@ public static String runProcessAndGetOutput(String command, String params) throw
      * This method checks that exec is a valid operating system command. Which commands are valid is system-dependent,
      * but at the very least the command must be a non-empty and non-null.
      * The subprocess inherits the environment settings of the current process.
-     * A minimal set of system dependent environment variables may be required to start a process on some operating systems.
+     * A minimal set of system dependent environment variables may be required to start a process on some operating
+     * systems.
      * The working directory of the new subprocess is specified by workingDirPath.
      * If dir is null, the subprocess inherits the current working directory of the current process.
      *
      * @param execPath a specified system command.
-     * @param params a parameters for the specifed system command.
+     * @param params   a parameters for the specifed system command.
      *
      * @return subprocess errors as {@code StringBuilder}.
      *
@@ -234,16 +254,17 @@ public static StringBuilder runProcessAndCollectErrors(String execPath, String p
      * This method checks that exec is a valid operating system command. Which commands are valid is system-dependent,
      * but at the very least the command must be a non-empty and non-null.
      * The subprocess inherits the environment settings of the current process.
-     * A minimal set of system dependent environment variables may be required to start a process on some operating systems.
+     * A minimal set of system dependent environment variables may be required to start a process on some operating
+     * systems.
      * The working directory of the new subprocess is specified by workingDirPath.
      * If dir is null, the subprocess inherits the current working directory of the current process.
      *
      * @param command a specified system command.
-     * @param params a parameters for the specifed system command.
+     * @param params  a parameters for the specifed system command.
      *
      * @return process info instance.
      *
-     * @throws IOException if any I/O error occurs.
+     * @throws IOException          if any I/O error occurs.
      * @throws InterruptedException if process was interrupted.
      */
     public static ProcessInfo runProcessAndGetProcessInfo(String command, String params) throws IOException,

commons/src/main/java/com/itextpdf/commons/utils/TimerUtil.java

@@ -0,0 +1,69 @@
+/*
+    This file is part of the iText (R) project.
+    Copyright (c) 1998-2025 Apryse Group NV
+    Authors: Apryse Software.
+
+    This program is offered under a commercial and under the AGPL license.
+    For commercial licensing, contact us at https://itextpdf.com/sales.  For AGPL licensing, see below.
+
+    AGPL licensing:
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.itextpdf.commons.utils;
+
+import java.util.Timer;
+
+/**
+ * Utility class for creating and managing timers.
+ */
+public class TimerUtil {
+
+    private TimerUtil() {
+        // Private constructor to prevent instantiation
+    }
+
+    /**
+     * Creates a new Timer instance.
+     *
+     * @param task   the task to be executed by the timer
+     * @param delay  the delay before the task is executed for the first time
+     * @param period the period between subsequent executions of the task
+     *
+     * @return a Timer instance that executes the task at the specified interval
+     */
+
+    public static Timer newTimerWithRecurringTask(Action task, long delay, long period) {
+        Timer t = new Timer(true);
+        t.scheduleAtFixedRate(new java.util.TimerTask() {
+            @Override
+            public void run() {
+                task.execute();
+            }
+        }, delay, period);
+        return t;
+    }
+
+    /**
+     * Stops the given Timer instance.
+     *
+     * @param timer the Timer instance to stop
+     */
+    public static void stopTimer(Timer timer) {
+        if (timer != null) {
+            timer.cancel();
+            timer.purge();
+        }
+    }
+
+}

commons/src/sharpenconfig/java/com/itextpdf/commons/SharpenConfigMapping.java

@@ -327,6 +327,12 @@ private void mapStandardJavaToUtil(MappingConfigurator configurator) {
         for (String name : streamImplementations) {
             configurator.addCustomUsingForMethodInvocation(name + ".sorted", Collections.singletonList("iText.Commons.Utils.Collections"));
         }
+
+
+
+        configurator.mapType("java.util.Timer", "System.Threading.Timer");
+        configurator.mapType("java.util.concurrent.Callable<>", "Func");
+        configurator.mapMethod("java.util.concurrent.Callable.call", "Invoke");
     }
 
     private void mapBouncyCastle(MappingConfigurator configurator) {