[MNG-8281] Interpolator service

api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactDeployerException.java

@@ -18,6 +18,8 @@
  */
 package org.apache.maven.api.services;
 
+import java.io.Serial;
+
 import org.apache.maven.api.annotations.Experimental;
 
 /**
@@ -31,6 +33,7 @@ public class ArtifactDeployerException extends MavenException {
     /**
      *
      */
+    @Serial
     private static final long serialVersionUID = 7421964724059077698L;
 
     /**

api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstallerException.java

@@ -18,6 +18,8 @@
  */
 package org.apache.maven.api.services;
 
+import java.io.Serial;
+
 import org.apache.maven.api.annotations.Experimental;
 
 /**
@@ -29,6 +31,7 @@ public class ArtifactInstallerException extends MavenException {
     /**
      *
      */
+    @Serial
     private static final long serialVersionUID = 3652561971360586373L;
 
     /**

api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolverException.java

@@ -18,6 +18,8 @@
  */
 package org.apache.maven.api.services;
 
+import java.io.Serial;
+
 import org.apache.maven.api.annotations.Experimental;
 
 /**
@@ -28,6 +30,7 @@
 @Experimental
 public class ArtifactResolverException extends MavenException {
 
+    @Serial
     private static final long serialVersionUID = 7252294837746943917L;
 
     /**

api/maven-api-core/src/main/java/org/apache/maven/api/services/ChecksumAlgorithmServiceException.java

@@ -18,11 +18,14 @@
  */
 package org.apache.maven.api.services;
 
+import java.io.Serial;
+
 import org.apache.maven.api.annotations.Experimental;
 
 @Experimental
 public class ChecksumAlgorithmServiceException extends MavenException {
 
+    @Serial
     private static final long serialVersionUID = 1201171469179367694L;
 
     public ChecksumAlgorithmServiceException(String message, Throwable cause) {

api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverException.java

@@ -18,11 +18,14 @@
  */
 package org.apache.maven.api.services;
 
+import java.io.Serial;
+
 import org.apache.maven.api.annotations.Experimental;
 
 @Experimental
 public class DependencyResolverException extends MavenException {
 
+    @Serial
     private static final long serialVersionUID = 1101171569179057614L;
 
     public DependencyResolverException(String message, Throwable cause) {

api/maven-api-core/src/main/java/org/apache/maven/api/services/Interpolator.java

@@ -0,0 +1,159 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.api.services;
+
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+import java.util.function.BiFunction;
+import java.util.function.Function;
+
+import org.apache.maven.api.Service;
+import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Nonnull;
+import org.apache.maven.api.annotations.Nullable;
+
+/**
+ * The Interpolator service provides methods for variable substitution in strings and maps.
+ * It allows for the replacement of placeholders (e.g., ${variable}) with their corresponding values.
+ *
+ * @since 4.0.0
+ */
+@Experimental
+public interface Interpolator extends Service {
+
+    /**
+     * Interpolates the values in the given map using the provided callback function.
+     * This method defaults to setting empty strings for unresolved placeholders.
+     *
+     * @param properties The map containing key-value pairs to be interpolated.
+     * @param callback The function to resolve variable values not found in the map.
+     */
+    default void interpolate(@Nonnull Map<String, String> properties, @Nullable Function<String, String> callback) {
+        interpolate(properties, callback, null, true);
+    }
+
+    /**
+     * Interpolates the values in the given map using the provided callback function.
+     *
+     * @param map The map containing key-value pairs to be interpolated.
+     * @param callback The function to resolve variable values not found in the map.
+     * @param defaultsToEmpty If true, unresolved placeholders are replaced with empty strings. If false, they are left unchanged.
+     */
+    default void interpolate(
+            @Nonnull Map<String, String> map, @Nullable Function<String, String> callback, boolean defaultsToEmpty) {
+        interpolate(map, callback, null, defaultsToEmpty);
+    }
+
+    /**
+     * Interpolates the values in the given map using the provided callback function.
+     *
+     * @param map The map containing key-value pairs to be interpolated.
+     * @param callback The function to resolve variable values not found in the map.
+     * @param defaultsToEmpty If true, unresolved placeholders are replaced with empty strings.  If false, they are left unchanged.
+     */
+    void interpolate(
+            @Nonnull Map<String, String> map,
+            @Nullable Function<String, String> callback,
+            @Nullable BiFunction<String, String, String> postprocessor,
+            boolean defaultsToEmpty);
+
+    /**
+     * Interpolates a single string value using the provided callback function.
+     * This method defaults to not replacing unresolved placeholders.
+     *
+     * @param val The string to be interpolated.
+     * @param callback The function to resolve variable values.
+     * @return The interpolated string, or null if the input was null.
+     */
+    @Nullable
+    default String interpolate(@Nullable String val, @Nullable Function<String, String> callback) {
+        return interpolate(val, callback, false);
+    }
+
+    /**
+     * Interpolates a single string value using the provided callback function.
+     *
+     * @param val The string to be interpolated.
+     * @param callback The function to resolve variable values.
+     * @param defaultsToEmpty If true, unresolved placeholders are replaced with empty strings.
+     * @return The interpolated string, or null if the input was null.
+     */
+    @Nullable
+    default String interpolate(
+            @Nullable String val, @Nullable Function<String, String> callback, boolean defaultsToEmpty) {
+        return interpolate(val, callback, null, defaultsToEmpty);
+    }
+
+    /**
+     * Interpolates a single string value using the provided callback function.
+     *
+     * @param val The string to be interpolated.
+     * @param callback The function to resolve variable values.
+     * @param defaultsToEmpty If true, unresolved placeholders are replaced with empty strings.
+     * @return The interpolated string, or null if the input was null.
+     */
+    @Nullable
+    String interpolate(
+            @Nullable String val,
+            @Nullable Function<String, String> callback,
+            @Nullable BiFunction<String, String, String> postprocessor,
+            boolean defaultsToEmpty);
+
+    /**
+     * Creates a composite function from a collection of functions.
+     *
+     * @param functions A collection of functions, each taking a String as input and returning a String.
+     * @return A function that applies each function in the collection in order until a non-null result is found.
+     *         If all functions return null, the composite function returns null.
+     *
+     * @throws NullPointerException if the input collection is null or contains null elements.
+     */
+    static Function<String, String> chain(Collection<? extends Function<String, String>> functions) {
+        return s -> {
+            for (Function<String, String> function : functions) {
+                String v = function.apply(s);
+                if (v != null) {
+                    return v;
+                }
+            }
+            return null;
+        };
+    }
+
+    /**
+     * Memoizes a given function that takes a String input and produces a String output.
+     * This method creates a new function that caches the results of the original function,
+     * improving performance for repeated calls with the same input.
+     *
+     * @param callback The original function to be memoized. It takes a String as input and returns a String.
+     * @return A new {@code Function<String, String>} that caches the results of the original function.
+     *         If the original function returns null for a given input, null will be cached and returned for subsequent calls with the same input.
+     *
+     * @see Function
+     * @see Optional
+     * @see HashMap#computeIfAbsent(Object, Function)
+     */
+    static Function<String, String> memoize(Function<String, String> callback) {
+        Map<String, Optional<String>> cache = new HashMap<>();
+        return s -> cache.computeIfAbsent(s, v -> Optional.ofNullable(callback.apply(v)))
+                .orElse(null);
+    }
+}

api/maven-api-core/src/main/java/org/apache/maven/api/services/InterpolatorException.java

@@ -0,0 +1,71 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.api.services;
+
+import java.io.Serial;
+
+import org.apache.maven.api.annotations.Experimental;
+
+/**
+ * Exception thrown by {@link Interpolator} implementations when an error occurs during interpolation.
+ * This can include syntax errors in variable placeholders or recursive variable references.
+ *
+ * @since 4.0.0
+ */
+@Experimental
+public class InterpolatorException extends MavenException {
+
+    @Serial
+    private static final long serialVersionUID = -1219149033636851813L;
+
+    /**
+     * Constructs a new InterpolatorException with {@code null} as its
+     * detail message. The cause is not initialized, and may subsequently be
+     * initialized by a call to {@link #initCause}.
+     */
+    public InterpolatorException() {}
+
+    /**
+     * Constructs a new InterpolatorException with the specified detail message.
+     * The cause is not initialized, and may subsequently be initialized by
+     * a call to {@link #initCause}.
+     *
+     * @param message the detail message. The detail message is saved for
+     *                later retrieval by the {@link #getMessage()} method.
+     */
+    public InterpolatorException(String message) {
+        super(message);
+    }
+
+    /**
+     * Constructs a new InterpolatorException with the specified detail message and cause.
+     *
+     * <p>Note that the detail message associated with {@code cause} is <i>not</i>
+     * automatically incorporated in this exception's detail message.</p>
+     *
+     * @param message the detail message (which is saved for later retrieval
+     *                by the {@link #getMessage()} method).
+     * @param cause   the cause (which is saved for later retrieval by the
+     *                {@link #getCause()} method). A {@code null} value is
+     *                permitted, and indicates that the cause is nonexistent or unknown.
+     */
+    public InterpolatorException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

api/maven-api-core/src/main/java/org/apache/maven/api/services/LookupException.java

@@ -18,6 +18,8 @@
  */
 package org.apache.maven.api.services;
 
+import java.io.Serial;
+
 import org.apache.maven.api.annotations.Experimental;
 
 /**
@@ -28,6 +30,9 @@
 @Experimental
 public class LookupException extends MavenException {
 
+    @Serial
+    private static final long serialVersionUID = -6259322450070320286L;
+
     public LookupException(String message) {
         super(message);
     }

api/maven-api-core/src/main/java/org/apache/maven/api/services/MavenException.java

@@ -18,6 +18,8 @@
  */
 package org.apache.maven.api.services;
 
+import java.io.Serial;
+
 import org.apache.maven.api.annotations.Experimental;
 
 /**
@@ -27,6 +29,10 @@
  */
 @Experimental
 public class MavenException extends RuntimeException {
+
+    @Serial
+    private static final long serialVersionUID = 9027638326336093132L;
+
     public MavenException() {}
 
     public MavenException(String message) {

api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilderException.java

@@ -18,6 +18,7 @@
  */
 package org.apache.maven.api.services;
 
+import java.io.Serial;
 import java.util.Collections;
 import java.util.List;
 
@@ -31,6 +32,9 @@
 @Experimental
 public class ModelBuilderException extends MavenException {
 
+    @Serial
+    private static final long serialVersionUID = -1865447022070650896L;
+
     private final ModelBuilderResult result;
 
     /**

api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilderException.java

@@ -18,6 +18,8 @@
  */
 package org.apache.maven.api.services;
 
+import java.io.Serial;
+
 import org.apache.maven.api.annotations.Experimental;
 
 /**
@@ -27,6 +29,10 @@
  */
 @Experimental
 public class ProjectBuilderException extends MavenException {
+
+    @Serial
+    private static final long serialVersionUID = -7629871850875943799L;
+
     /**
      * @param message the message to give
      * @param e the {@link Exception}