Xpath builtin function and readme yaml (#2485)

* feat: move SpEL built-in functions to CommonBuiltInFunctions; add XPath support and tests

- Removed `BuiltInFunctions` and integrated its logic into `CommonBuiltInFunctions` for better modularity.
- Introduced support for XPath evaluation in `CommonBuiltInFunctions` using `javax.xml.xpath`.
- Updated SpEL and Groovy built-in functions to include XPath support.
- Added comprehensive unit tests for XPath functionality and updated README with usage examples.

* add `@SuppressWarnings("unused")` to Groovy and SpEL built-in functions and optimize imports in SpEL test

* make `SpELBuiltInFunctions#jsonPath` method static for better utility usage

* refactor: centralize error handling in `AbstractSetterInterceptor` and enhance `ExchangeExpressionException` with detailed messages and stacktrace control

- Moved redundant error handling logic in `AbstractSetterInterceptor` to a dedicated method for improved readability and maintainability.
- Updated `ExchangeExpressionException` to support detailed error messages and enable/disable stacktraces.
- Introduced `getBuiltInFunctionNames` in `SpELBuiltInFunctions` to provide a list of supported SpEL functions for use in error messages.
- Enhanced logging clarity for expression evaluation errors.

* refactor: remove `stacktrace` property and simplify error handling in `ExchangeExpressionException`

- Eliminated unused `stacktrace` field and its associated methods.
- Updated `ExchangeExpressionException` and related classes to streamline error reporting.
- Fixed minor wording in README example configuration.

* fix: replace string matching with `getMessageCode` in SpEL exception handling for improved clarity

- Used `METHOD_NOT_FOUND` constant instead of string matching for detecting method-not-found errors in SpEL expressions.

---------

Co-authored-by: Christian Gördes <118011644+christiangoerdes@users.noreply.github.com>

Author: predic8

README.md

@@ -747,18 +747,18 @@ api:
 
 ### Transform XML into Text or JSON
 
-Using `setProperty` you can extract values from XML request or response bodies and store it in properties. Then the properties are available as variables inside the `template` plugin.
-plugin.
+You can use XPath to extract values from an XML message and insert them into a `template`.
 
-```xml
-
-<api port="2000">
-    <request>
-        <setProperty name="fn" value="${/person/@firstname}" language="xpath"/>
-        <template>Buenas Noches, ${property.fn}sito!</template>
-    </request>
-    <return/>
-</api>
+```yaml
+api:
+  port: 2000
+  flow:
+    - request:
+        - template:
+            src: |
+              Buenas noches, ${fn.xpath('/person/@firstname')}
+        - return:
+            status: 200
 ```
 
 See: [message-transformation examples](./distribution/examples/message-transformation)
@@ -876,7 +876,7 @@ Membrane offers lots of security features to protect backend servers.
 You can define APIs keys directly in your configuration, and Membrane will validate incoming requests against them.
 
 ### Example Configuration
-The following configuration secures the `Fruitshop API` by validating a key provided as a query parameter:
+The following configuration secures the `Fruitshop API` by validating an API key provided as a query parameter:
 
 ```xml
 <api port="2000">

core/src/main/java/com/predic8/membrane/core/exceptions/ProblemDetails.java

@@ -54,6 +54,8 @@ public class ProblemDetails {
     public static final String MESSAGE = "message";
     public static final String STACK_TRACE = "stackTrace";
     public static final String LOG_KEY = "logKey";
+    public static final String DEVELOPMENT_MODE_WARNING = """
+            Membrane is in development mode. For production set <router production="true"> to reduce details in error messages!""";
 
     /**
      * If router is in production mode that should not expose internal details
@@ -136,9 +138,6 @@ public static ProblemDetails problemDetails(String type, boolean production) {
     /**
      * type/subtype/subtype/...
      * lowercase, dash as separator
-     *
-     * @param subType
-     * @return
      */
     public ProblemDetails addSubType(String subType) {
         this.subType += "/" + subType;
@@ -300,8 +299,7 @@ private Map<String, Object> createInternal(String type) {
             }
         }
         internalMap.put(SEE, getFullType(type));
-        internalMap.put(ATTENTION, """
-                Membrane is in development mode. For production set <router production="true"> to reduce details in error messages!""");
+        internalMap.put(ATTENTION, DEVELOPMENT_MODE_WARNING);
         return internalMap;
     }
 

core/src/main/java/com/predic8/membrane/core/interceptor/lang/AbstractSetterInterceptor.java

@@ -15,8 +15,10 @@
 package com.predic8.membrane.core.interceptor.lang;
 
 import com.predic8.membrane.annot.*;
+import com.predic8.membrane.core.exceptions.*;
 import com.predic8.membrane.core.exchange.*;
 import com.predic8.membrane.core.interceptor.*;
+import com.predic8.membrane.core.lang.*;
 import com.predic8.membrane.core.util.*;
 import org.slf4j.*;
 
@@ -51,25 +53,32 @@ private Outcome handleInternal(Exchange exchange, Flow flow) {
         try {
             setValue(exchange, flow, exchangeExpression.evaluate(exchange, flow, getExpressionReturnType()));
         } catch (Exception e) {
-            var root = ExceptionUtil.getRootCause(e);
-            var message = "While evaluating expression %s for field %s: %s".formatted(expression, fieldName, root.getMessage());
-            log.info(message);
-
+            var msg = "Error evaluating expression %s for field %s".formatted(expression, fieldName);
             if (failOnError) {
-                internal(getRouter().isProduction(), getDisplayName())
-                        .title("Error evaluating expression!")
-                        .internal("field", fieldName)
-                        .internal("expression", expression)
-                        .exception(root)
+                if (e instanceof ExchangeExpressionException eee) {
+                    var pd = prepareProblemDetails(msg);
+                    eee.provideDetails(pd);
+                    pd.buildAndSetResponse(exchange);
+                    return ABORT;
+                }
+                prepareProblemDetails(msg)
+                        .exception(ExceptionUtil.getRootCause(e))
                         .stacktrace(false)
                         .buildAndSetResponse(exchange);
                 return ABORT;
             }
-            log.info("Error evaluating {} but 'FailOnError' is false therefore ignoring: {}", expression, message);
+            log.info("'FailOnError' is false therefore ignoring: {}", msg);
         }
         return CONTINUE;
     }
 
+    private ProblemDetails prepareProblemDetails(String msg) {
+        return internal(getRouter().isProduction(), getDisplayName())
+                .title(msg)
+                .internal("field", fieldName)
+                .internal("expression", expression);
+    }
+
     protected abstract Class<?> getExpressionReturnType();
 
     protected abstract boolean shouldSetValue(Exchange exchange, Flow flow);

core/src/main/java/com/predic8/membrane/core/lang/CommonBuiltInFunctions.java

@@ -14,29 +14,28 @@
 
 package com.predic8.membrane.core.lang;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.jayway.jsonpath.JsonPath;
-import com.predic8.membrane.core.exchange.Exchange;
-import com.predic8.membrane.core.http.Message;
-import com.predic8.membrane.core.interceptor.AbstractInterceptorWithSession;
+import com.fasterxml.jackson.databind.*;
+import com.jayway.jsonpath.*;
+import com.predic8.membrane.core.exchange.*;
+import com.predic8.membrane.core.http.*;
+import com.predic8.membrane.core.interceptor.*;
 import com.predic8.membrane.core.interceptor.Interceptor.Flow;
-import com.predic8.membrane.core.security.BasicHttpSecurityScheme;
-import com.predic8.membrane.core.security.SecurityScheme;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
-import java.util.Collection;
-import java.util.List;
-import java.util.Map;
-import java.util.Optional;
-import java.util.concurrent.ThreadLocalRandom;
+import com.predic8.membrane.core.lang.spel.*;
+import com.predic8.membrane.core.security.*;
+import com.predic8.membrane.core.util.xml.*;
+import com.predic8.membrane.core.util.xml.parser.*;
+import org.slf4j.*;
+
+import javax.xml.xpath.*;
+import java.util.*;
+import java.util.concurrent.*;
 import java.util.function.Predicate;
 
-import static com.predic8.membrane.core.exchange.Exchange.SECURITY_SCHEMES;
-import static com.predic8.membrane.core.http.Header.AUTHORIZATION;
-import static java.nio.charset.StandardCharsets.UTF_8;
-import static java.util.Collections.emptyList;
-import static java.util.Objects.requireNonNull;
+import static com.predic8.membrane.core.exchange.Exchange.*;
+import static com.predic8.membrane.core.http.Header.*;
+import static java.nio.charset.StandardCharsets.*;
+import static java.util.Collections.*;
+import static java.util.Objects.*;
 
 /**
  * Place to share built-in functions between SpEL and Groovy.
@@ -47,6 +46,9 @@ public class CommonBuiltInFunctions {
 
     private static final ObjectMapper objectMapper = new ObjectMapper();
 
+    private static final XPathFactory xPathFactory = XPathFactory.newInstance();
+    private static final XmlParser parser = HardenedXmlParser.getInstance();
+
     public static Object jsonPath(String jsonPath, Message msg) {
         try {
             return JsonPath.read(objectMapper.readValue(msg.getBodyAsStringDecoded(), Map.class), jsonPath);
@@ -55,9 +57,25 @@ public static Object jsonPath(String jsonPath, Message msg) {
         }
     }
 
+    public static String xpath(String xpath, Message message) {
+        XPath xPath = xPathFactory.newXPath();
+
+        // TODO: Leave the comment in till the XML namespace support is realized!
+        // - When there is the new registry use it to obtain the XMLConfig.
+        //        if (xmlConfig != null && xmlConfig.getNamespaces() != null) {
+        //            xPath.setNamespaceContext(xmlConfig.getNamespaces().getNamespaceContext());
+        //        }
+
+        try {
+            return xPath.evaluate(xpath, parser.parse(XMLUtil.getInputSource(message)), XPathConstants.STRING).toString();
+        } catch (XPathExpressionException ignored) {
+            return null;
+        }
+    }
+
     public static String user(Exchange exchange) {
-        List<SecurityScheme> schemes = exchange.getProperty(SECURITY_SCHEMES, List.class );
-        for (SecurityScheme scheme :schemes) {
+        List<SecurityScheme> schemes = exchange.getProperty(SECURITY_SCHEMES, List.class);
+        for (SecurityScheme scheme : schemes) {
             if (scheme instanceof BasicHttpSecurityScheme basic) {
                 return basic.getUsername();
             }
@@ -100,7 +118,7 @@ public static String base64Encode(String s) {
 
     public static boolean isBearerAuthorization(Exchange exc) {
         return exc.getRequest().getHeader().contains(AUTHORIZATION)
-                && exc.getRequest().getHeader().getFirstValue(AUTHORIZATION).startsWith("Bearer");
+               && exc.getRequest().getHeader().getFirstValue(AUTHORIZATION).startsWith("Bearer");
     }
 
     private static List<String> getSchemeScopes(Predicate<SecurityScheme> predicate, Exchange exc) {

core/src/main/java/com/predic8/membrane/core/lang/ExchangeExpressionException.java

@@ -21,8 +21,7 @@ public class ExchangeExpressionException extends RuntimeException {
 
     private final String expression;
     private final Map<String, Object> extensions = new HashMap<>();
-
-    private boolean statcktrace = true;
+    private String detail;
 
     /*
      * Body that cause the error
@@ -39,8 +38,9 @@ public ExchangeExpressionException(String expression, Throwable cause) {
      * @return ProblemDetails filled from exception
      */
     public ProblemDetails provideDetails(ProblemDetails pd) {
-        pd.internal("expression", expression)
-            .stacktrace(statcktrace);
+        if (detail != null)
+            pd.detail(detail);
+        pd.internal("expression", expression);
         for (Map.Entry<String, Object> entry : extensions.entrySet()) {
             pd.internal(entry.getKey(), entry.getValue());
         }
@@ -51,6 +51,11 @@ public ProblemDetails provideDetails(ProblemDetails pd) {
         return pd;
     }
 
+    public ExchangeExpressionException detail(String detail) {
+        this.detail = detail;
+        return this;
+    }
+
     public ExchangeExpressionException extension(String key, Object value) {
         extensions.put(key, value);
         return this;
@@ -66,11 +71,6 @@ public ExchangeExpressionException column(String column) {
         return this;
     }
 
-    public ExchangeExpressionException stacktrace(boolean stacktrace) {
-        this.statcktrace = stacktrace;
-        return this;
-    }
-
     public ExchangeExpressionException body(String body) {
         this.body = body;
         return this;

core/src/main/java/com/predic8/membrane/core/lang/groovy/GroovyBuiltInFunctions.java

@@ -26,6 +26,7 @@
  *  Difference to SpEL:
  *  The functions are called with ${fn.functionname()} instead of ${functionname()} in the template interceptor
  */
+@SuppressWarnings("unused")
 public class GroovyBuiltInFunctions extends GroovyObjectSupport {
 
     private final Exchange exchange;
@@ -45,6 +46,10 @@ public Object jsonPath(String jsonPath) {
         return CommonBuiltInFunctions.jsonPath(jsonPath, exchange.getMessage(flow));
     }
 
+    public String xpath(String xpath) {
+        return CommonBuiltInFunctions.xpath(xpath, exchange.getMessage(flow));
+    }
+
     public List<String> scopes() {
         return CommonBuiltInFunctions.scopes(exchange);
     }
@@ -69,6 +74,8 @@ public boolean isXML() {
         return CommonBuiltInFunctions.isXML(exchange, flow);
     }
 
+
+
     public boolean isJSON() {
         return CommonBuiltInFunctions.isJSON(exchange, flow);
     }

core/src/main/java/com/predic8/membrane/core/lang/spel/SpELExchangeExpression.java

@@ -30,6 +30,7 @@
 
 import static java.lang.Boolean.*;
 import static org.springframework.expression.spel.SpelCompilerMode.*;
+import static org.springframework.expression.spel.SpelMessage.METHOD_NOT_FOUND;
 
 public class SpELExchangeExpression extends AbstractExchangeExpression {
 
@@ -82,13 +83,19 @@ public <T> T evaluate(Exchange exchange, Flow flow, Class<T> type) {
             }
             throw new RuntimeException("Cannot cast %s to %s".formatted(o,type));
         } catch (SpelEvaluationException see) {
-            log.error("Error in expression '{}': {}",expression, see.getLocalizedMessage());
             ExchangeExpressionException eee = new ExchangeExpressionException(expression, see);
-            if (see.getCause() instanceof ConverterNotFoundException cnfe) {
+            String msg ;
+            if (see.getMessageCode() == METHOD_NOT_FOUND) {
+                msg = "Method not found in expression '%s' use a SpEL function or one of Membrane's: %s".formatted(expression, SpELBuiltInFunctions.getBuiltInFunctionNames());
+            } else if (see.getCause() instanceof ConverterNotFoundException cnfe) {
+                msg = "Type converter not found for expression '%s' from '%s' to '%s'.".formatted(expression, cnfe.getSourceType(), cnfe.getTargetType());
                 eee.extension("sourceType", cnfe.getSourceType())
                         .extension("targetType", cnfe.getTargetType());
+            } else {
+                msg = "Error in expression '%s': %s".formatted( expression, see.getMessage());
             }
-            eee.stacktrace(false);
+            log.warn(msg);
+            eee.detail(msg);
             throw eee;
         }
     }