This is an automated email from the ASF dual-hosted git repository.

rmannibucau pushed a commit to branch dev/cleanup-error-message
in repository https://gitbox.apache.org/repos/asf/maven.git

commit faaf46983770d97be279629f1007f1e25db61347
Author: Romain Manni-Bucau <[email protected]>
AuthorDate: Wed Nov 11 00:10:16 2026 +0100

    perf: avoid reading error help resources unless verbose
    
    Address review feedback on the embedded error help text:
    - add ReferenceHelp.hasHelpText(String) as a cheap existence-only check
      that does not open or read the resource content
    - use hasHelpText() where only the null-check mattered, dropping the
      wasted getResourceAsStream()+readAllBytes() on the error path
    - guard the debug-level help output in MavenCli with isDebugEnabled()
      and in MavenInvoker with effectiveVerbose() so the resource is only
      read when it will actually be logged
    - document the source-breaking logSummary(...) signature change
      (the References collector map parameter was dropped)
---
 .../main/java/org/apache/maven/cli/MavenCli.java   | 12 ++++-----
 .../maven/cling/invoker/mvn/MavenInvoker.java      | 26 ++++++++++++++-----
 .../org/apache/maven/exception/ReferenceHelp.java  | 14 +++++++++++
 .../apache/maven/exception/ReferenceHelpTest.java  | 29 ++++++++++++++++++++++
 4 files changed, 69 insertions(+), 12 deletions(-)

diff --git 
a/compat/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java 
b/compat/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java
index e1740f6185..1e4eafcabe 100644
--- a/compat/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java
+++ b/compat/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java
@@ -1116,7 +1116,7 @@ private int execute(CliRequest cliRequest) throws 
MavenExecutionRequestPopulatio
             for (Throwable exception : result.getExceptions()) {
                 ExceptionSummary summary = handler.handleException(exception);
 
-                hasDetailedHelp |= 
ReferenceHelp.getHelpText(summary.getReference()) != null;
+                hasDetailedHelp |= 
ReferenceHelp.hasHelpText(summary.getReference());
 
                 logSummary(summary, "", cliRequest.showErrors);
 
@@ -1241,11 +1241,11 @@ private void logSummary(ExceptionSummary summary, 
String indent, boolean showErr
         }
 
         String reference = summary.getReference();
-        if (reference != null && !reference.isEmpty()) {
-            String help = ReferenceHelp.getHelpText(reference);
-            if (help != null) {
-                slf4jLogger.debug(help);
-            }
+        if (reference != null
+                && !reference.isEmpty()
+                && slf4jLogger.isDebugEnabled()
+                && ReferenceHelp.hasHelpText(reference)) {
+            slf4jLogger.debug(ReferenceHelp.getHelpText(reference));
         }
 
         indent += "  ";
diff --git 
a/impl/maven-cli/src/main/java/org/apache/maven/cling/invoker/mvn/MavenInvoker.java
 
b/impl/maven-cli/src/main/java/org/apache/maven/cling/invoker/mvn/MavenInvoker.java
index 07a1fa18d2..fcfb4da956 100644
--- 
a/impl/maven-cli/src/main/java/org/apache/maven/cling/invoker/mvn/MavenInvoker.java
+++ 
b/impl/maven-cli/src/main/java/org/apache/maven/cling/invoker/mvn/MavenInvoker.java
@@ -479,7 +479,7 @@ protected int doExecute(MavenContext context, 
MavenExecutionRequest request) thr
             Set<String> hintedArtifacts = new HashSet<>();
             for (Throwable exception : result.getExceptions()) {
                 ExceptionSummary summary = handler.handleException(exception);
-                hasDetailedHelp |= 
ReferenceHelp.getHelpText(summary.getReference()) != null;
+                hasDetailedHelp |= 
ReferenceHelp.hasHelpText(summary.getReference());
                 logSummary(context, summary, "");
 
                 if (exception instanceof LifecycleExecutionException 
lifecycleExecutionException) {
@@ -637,6 +637,20 @@ protected String getResumeFromSelector(List<MavenProject> 
mavenProjects, MavenPr
 
     protected static final String ANSI_RESET = "\u001B\u005Bm";
 
+    /**
+     * Logs the summary of a failed build, including any embedded detailed 
help text associated with
+     * {@link ExceptionSummary#getReference()} when verbose output is enabled.
+     * <p>
+     * Migration note: the former {@code logSummary(MavenContext, 
ExceptionSummary, Map<String, String>,
+     * String)} overload (which collected the reference URLs into a {@code 
references} map) was replaced by
+     * this three-argument form. The collector map has been dropped: detailed 
help is now read on demand from
+     * the {@link ReferenceHelp} resources instead. Subclasses overriding the 
old overload must update to this
+     * signature.
+     *
+     * @param context the Maven context used for logging
+     * @param summary the exception summary to log
+     * @param indent the indentation prefix for nested summary lines
+     */
     protected void logSummary(MavenContext context, ExceptionSummary summary, 
String indent) {
         String msg = summary.getMessage();
 
@@ -673,11 +687,11 @@ protected void logSummary(MavenContext context, 
ExceptionSummary summary, String
         }
 
         String reference = summary.getReference();
-        if (reference != null && !reference.isEmpty()) {
-            String help = ReferenceHelp.getHelpText(reference);
-            if (help != null) {
-                context.logger.debug(help);
-            }
+        if (reference != null
+                && !reference.isEmpty()
+                && context.invokerRequest.effectiveVerbose()
+                && ReferenceHelp.hasHelpText(reference)) {
+            context.logger.debug(ReferenceHelp.getHelpText(reference));
         }
 
         indent += "  ";
diff --git 
a/impl/maven-core/src/main/java/org/apache/maven/exception/ReferenceHelp.java 
b/impl/maven-core/src/main/java/org/apache/maven/exception/ReferenceHelp.java
index 645e6971e6..7caa5d2b07 100644
--- 
a/impl/maven-core/src/main/java/org/apache/maven/exception/ReferenceHelp.java
+++ 
b/impl/maven-core/src/main/java/org/apache/maven/exception/ReferenceHelp.java
@@ -72,6 +72,20 @@ public static String getHelpText(String reference) {
         }
     }
 
+    /**
+     * Returns whether a help text resource exists for the given exception 
reference. This is a cheap
+     * existence-only check that does not read the resource content; use it 
when only knowing whether a
+     * reference is backed by help text matters (for example to decide whether 
to hint at the verbose
+     * {@code -X} switch), and call {@link #getHelpText(String)} only when the 
text is actually needed.
+     *
+     * @param reference the exception reference, may be {@code null} or empty
+     * @return {@code true} when a help text resource exists for the 
reference, {@code false} otherwise
+     */
+    public static boolean hasHelpText(String reference) {
+        String key = normalizeKey(reference);
+        return key != null && ReferenceHelp.class.getResource(RESOURCE_PREFIX 
+ key + ".txt") != null;
+    }
+
     /**
      * Extracts the resource key from a reference (plain key or wiki URL) and 
validates it is safe to use
      * as a file name. Returns {@code null} when the reference cannot be 
mapped to a resource.
diff --git 
a/impl/maven-core/src/test/java/org/apache/maven/exception/ReferenceHelpTest.java
 
b/impl/maven-core/src/test/java/org/apache/maven/exception/ReferenceHelpTest.java
index 00f4aed0e6..4cb68da5aa 100644
--- 
a/impl/maven-core/src/test/java/org/apache/maven/exception/ReferenceHelpTest.java
+++ 
b/impl/maven-core/src/test/java/org/apache/maven/exception/ReferenceHelpTest.java
@@ -23,6 +23,7 @@
 import org.junit.jupiter.api.Test;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
@@ -94,6 +95,34 @@ void unknownReferencesProduceNoHelpText() {
         assertNull(ReferenceHelp.getHelpText(null));
     }
 
+    @Test
+    void hasHelpTextReturnsTrueForBuiltInReferences() {
+        for (String key : BUILT_IN_KEYS) {
+            assertTrue(ReferenceHelp.hasHelpText(key), "Expected help text 
resource for " + key);
+            assertTrue(
+                    
ReferenceHelp.hasHelpText("http://cwiki.apache.org/confluence/display/MAVEN/"; + 
key),
+                    "Expected help text resource for cwiki URL of " + key);
+        }
+        assertTrue(ReferenceHelp.hasHelpText(
+                
"https://maven.apache.org/resolver/remote-repository-filtering.html";));
+    }
+
+    @Test
+    void hasHelpTextReturnsFalseForUnknownOrInvalidReferences() {
+        assertFalse(ReferenceHelp.hasHelpText("NoSuchException"));
+        assertFalse(ReferenceHelp.hasHelpText("com.example.SomeError"));
+        assertFalse(ReferenceHelp.hasHelpText("a b"));
+        assertFalse(ReferenceHelp.hasHelpText(""));
+        assertFalse(ReferenceHelp.hasHelpText(null));
+    }
+
+    @Test
+    void hasHelpTextAgreesWithGetHelpTextForBuiltIns() {
+        for (String key : BUILT_IN_KEYS) {
+            assertEquals(ReferenceHelp.getHelpText(key) != null, 
ReferenceHelp.hasHelpText(key), key);
+        }
+    }
+
     @Test
     void helpTextIsTrimmed() {
         String help = ReferenceHelp.getHelpText("AetherClassNotFound");

Reply via email to