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");
