gnodet-bot commented on code in PR #14066: URL: https://github.com/apache/maven/pull/14066#discussion_r4642300904
########## api/maven-api-log/src/main/java/org/apache/maven/api/logging/LogEventBuilder.java: ########## @@ -0,0 +1,194 @@ +/* + * 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.logging; + +import org.apache.maven.api.annotations.Experimental; +import org.apache.maven.api.annotations.Nonnull; + +/** + * Fluent builder for a single log statement. + * <p> + * Instances are obtained from {@link Logger#atTrace()}, {@link Logger#atDebug()}, etc. + * A builder <em>must</em> be consumed in a single chained call; it must not be + * stored in a variable across statements, as implementations may reuse + * thread-local state for zero-allocation dispatch. + * <p> + * When the target level is disabled the {@code Logger} returns a shared + * {@code NopLogEventBuilder} singleton, making the entire fluent call chain a no-op + * with zero allocations. + * + * <pre>{@code + * log.atInfo() + * .withKeyValue("module", module.getId()) + * .log("Compiling {} source files", count); + * }</pre> + * + * <h2>Message format</h2> + * <p> + * The {@code log(String format, Object...)} family of methods uses a simple + * positional placeholder syntax: each occurrence of {@code {}} in the format + * string is replaced, in order, by the string representation of the corresponding + * argument. No index, type specifier, or locale conversion is supported — this is + * intentionally simpler than {@link java.text.MessageFormat} and avoids the + * injection risk of {@code printf}-style specifiers. + * <p> + * Example: {@code log("Building {} module(s) in {}", count, dir)} produces + * {@code "Building 3 module(s) in /tmp/build"} when {@code count=3} and + * {@code dir="/tmp/build"}. + * <p> + * This convention is the same as the one used by SLF4J + * (<a href="https://www.slf4j.org/api/org/slf4j/helpers/MessageFormatter.html">MessageFormatter</a>), + * which is widely used in the Java ecosystem and is already the format employed + * by {@code plugin.Log}, the API this interface replaces. + * + * @since 4.0.0 + */ +@Experimental +public interface LogEventBuilder { + + /** + * Attaches a structured key-value pair to this log event. + * <p> + * Structured key-value pairs are consumed by structured log appenders + * (e.g. JSON, ECS, or Logstash layouts in Logback or Log4j 2) that capture + * fields alongside the message text — rather than embedding metadata inside the + * message string itself. This enables log aggregators such as Elasticsearch or + * Splunk to filter and correlate events by field values directly. + * <p> + * In a Maven context, typical uses include attaching build metadata such as + * project coordinates, mojo identifiers, and elapsed time as first-class indexed + * fields. When running with a plain-text appender these pairs are silently ignored + * or appended after the message, depending on the appender configuration. + * + * @param key the field name, never {@code null} + * @param value the string value + * @return this builder + */ + @Nonnull + LogEventBuilder withKeyValue(@Nonnull String key, String value); + + /** + * Attaches a structured key-value pair with a {@code long} value. + * <p> + * See {@link #withKeyValue(String, String)} for the purpose of structured key-value pairs. + * + * @param key the field name, never {@code null} + * @param value the numeric value + * @return this builder + */ + @Nonnull + LogEventBuilder withKeyValue(@Nonnull String key, long value); + + /** + * Attaches a structured key-value pair with a {@code boolean} value. + * <p> + * See {@link #withKeyValue(String, String)} for the purpose of structured key-value pairs. + * + * @param key the field name, never {@code null} + * @param value the boolean value + * @return this builder + */ + @Nonnull + LogEventBuilder withKeyValue(@Nonnull String key, boolean value); + + /** + * Attaches a {@link Throwable} to this log event. + * + * @param t the throwable, may be {@code null} (no-op) + * @return this builder + */ + @Nonnull + LogEventBuilder withThrowable(Throwable t); Review Comment: ⚠️ **Missing `@Nullable` on parameter** — the Javadoc says `@param t the throwable, may be {@code null} (no-op)` but the parameter has no `@Nullable` annotation. `LogEventBuilder.java` only imports `@Nonnull`; `@Nullable` must be added to the import block too. Without it, IntelliJ/SpotBugs null-analysis produces a false-positive warning when callers pass `null` to clear the throwable. ```suggestion LogEventBuilder withThrowable(@Nullable Throwable t); ``` And add to the imports: ``` import org.apache.maven.api.annotations.Nullable; ``` ########## api/maven-api-log/src/main/java/org/apache/maven/api/logging/Logger.java: ########## @@ -0,0 +1,350 @@ +/* + * 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.logging; + +import java.util.function.Supplier; + +import org.apache.maven.api.annotations.Experimental; +import org.apache.maven.api.annotations.Nonnull; +import org.apache.maven.api.annotations.Nullable; +import org.apache.maven.api.annotations.Provider; + +/** + * Unified logging interface for Maven plugins and CLI bootstrap code. + * <p> + * Unified interface that supports a fluent builder API, structured key-value + * pairs, and lazy message evaluation. Used by both mojo logging and CLI + * bootstrap logging. + * <p> + * Instances are obtained via dependency injection. A {@code @Singleton} bean + * may hold a long-lived {@code Logger} instance safely: context fields such as + * {@code projectId} and {@code mojoId} are resolved from a per-thread + * {@code LogContext} at event dispatch time, not at injection time. Review Comment: ⚠️ **`LogContext` does not exist** — "context fields such as `projectId` and `mojoId` are resolved from a per-thread `LogContext` at event dispatch time, not at injection time." `LogContext` is not defined anywhere in this repository. Remove this claim; callers who read it will expect ThreadLocal-based context enrichment that the implementation does not provide. ########## api/maven-api-log/src/main/java/org/apache/maven/api/logging/LogEventBuilder.java: ########## @@ -0,0 +1,194 @@ +/* + * 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.logging; + +import org.apache.maven.api.annotations.Experimental; +import org.apache.maven.api.annotations.Nonnull; + +/** + * Fluent builder for a single log statement. + * <p> + * Instances are obtained from {@link Logger#atTrace()}, {@link Logger#atDebug()}, etc. + * A builder <em>must</em> be consumed in a single chained call; it must not be + * stored in a variable across statements, as implementations may reuse + * thread-local state for zero-allocation dispatch. + * <p> + * When the target level is disabled the {@code Logger} returns a shared + * {@code NopLogEventBuilder} singleton, making the entire fluent call chain a no-op + * with zero allocations. + * + * <pre>{@code + * log.atInfo() + * .withKeyValue("module", module.getId()) + * .log("Compiling {} source files", count); + * }</pre> + * + * <h2>Message format</h2> + * <p> + * The {@code log(String format, Object...)} family of methods uses a simple + * positional placeholder syntax: each occurrence of {@code {}} in the format + * string is replaced, in order, by the string representation of the corresponding + * argument. No index, type specifier, or locale conversion is supported — this is + * intentionally simpler than {@link java.text.MessageFormat} and avoids the + * injection risk of {@code printf}-style specifiers. + * <p> + * Example: {@code log("Building {} module(s) in {}", count, dir)} produces + * {@code "Building 3 module(s) in /tmp/build"} when {@code count=3} and + * {@code dir="/tmp/build"}. + * <p> + * This convention is the same as the one used by SLF4J + * (<a href="https://www.slf4j.org/api/org/slf4j/helpers/MessageFormatter.html">MessageFormatter</a>), + * which is widely used in the Java ecosystem and is already the format employed + * by {@code plugin.Log}, the API this interface replaces. + * + * @since 4.0.0 + */ +@Experimental +public interface LogEventBuilder { + + /** + * Attaches a structured key-value pair to this log event. + * <p> + * Structured key-value pairs are consumed by structured log appenders + * (e.g. JSON, ECS, or Logstash layouts in Logback or Log4j 2) that capture + * fields alongside the message text — rather than embedding metadata inside the + * message string itself. This enables log aggregators such as Elasticsearch or + * Splunk to filter and correlate events by field values directly. + * <p> + * In a Maven context, typical uses include attaching build metadata such as + * project coordinates, mojo identifiers, and elapsed time as first-class indexed + * fields. When running with a plain-text appender these pairs are silently ignored + * or appended after the message, depending on the appender configuration. + * + * @param key the field name, never {@code null} + * @param value the string value + * @return this builder + */ + @Nonnull + LogEventBuilder withKeyValue(@Nonnull String key, String value); + + /** + * Attaches a structured key-value pair with a {@code long} value. + * <p> + * See {@link #withKeyValue(String, String)} for the purpose of structured key-value pairs. + * + * @param key the field name, never {@code null} + * @param value the numeric value + * @return this builder + */ + @Nonnull + LogEventBuilder withKeyValue(@Nonnull String key, long value); + + /** + * Attaches a structured key-value pair with a {@code boolean} value. + * <p> + * See {@link #withKeyValue(String, String)} for the purpose of structured key-value pairs. + * + * @param key the field name, never {@code null} + * @param value the boolean value + * @return this builder + */ + @Nonnull + LogEventBuilder withKeyValue(@Nonnull String key, boolean value); + + /** + * Attaches a {@link Throwable} to this log event. + * + * @param t the throwable, may be {@code null} (no-op) + * @return this builder + */ + @Nonnull + LogEventBuilder withThrowable(Throwable t); + + /** + * Overrides the project identifier for this event. + * <p> + * The default path resolves {@code projectId} from the current thread's + * {@code LogContext}; use this method only in the rare cases where the + * ThreadLocal context is incorrect (e.g. async hand-offs). Review Comment: ⚠️ **`LogContext` does not exist** — this description says "The default path resolves `projectId` from the current thread's `LogContext`; use this method only in the rare cases where the ThreadLocal context is incorrect (e.g. async hand-offs)." But `LogContext` is not defined anywhere in this repository, and `DefaultLogEventBuilder.withProjectId` is a silent no-op (`return this`). This description inverts the truth: it implies enrichment happens automatically and this method is for overriding it, when in fact enrichment never happens at all. The description should match the actual implementation — that enrichment is best-effort and the built-in implementation silently ignores the value. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
