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

slachiewicz pushed a commit to branch plugin-logger-4.0
in repository https://gitbox.apache.org/repos/asf/maven.git

commit de347f3ddc337ce828ce15e5f8ea8820f4b3b4f7
Author: Guillaume Nodet <[email protected]>
AuthorDate: Wed Nov 18 10:29:44 2026 +0100

    logging: introduce Logger/LogEventBuilder/LogLevel API (from #13832)
---
 api/maven-api-log/pom.xml                          |  48 +++
 api/maven-api-log/src/main/java/module-info.java   |  26 ++
 .../apache/maven/api/logging/LogEventBuilder.java  | 153 ++++++++
 .../org/apache/maven/api/logging/LogLevel.java     |  42 +++
 .../java/org/apache/maven/api/logging/Logger.java  | 393 +++++++++++++++++++++
 .../org/apache/maven/api/logging/package-info.java | 122 +++++++
 6 files changed, 784 insertions(+)

diff --git a/api/maven-api-log/pom.xml b/api/maven-api-log/pom.xml
new file mode 100644
index 0000000000..f55f7b4ed1
--- /dev/null
+++ b/api/maven-api-log/pom.xml
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  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.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0"; 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; 
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
http://maven.apache.org/xsd/maven-4.0.0.xsd";>
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.apache.maven</groupId>
+    <artifactId>maven-api</artifactId>
+    <version>4.2.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>maven-api-log</artifactId>
+  <name>Maven 4 API :: Logging</name>
+  <description>Maven 4 API - Unified Logging API (Logger, LogEventBuilder, 
LogLevel, LogEvent, LogSink).</description>
+
+  <properties>
+    <javaModuleName>org.apache.maven.api.logging</javaModuleName>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.apache.maven</groupId>
+      <artifactId>maven-api-annotations</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-api</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+</project>
diff --git a/api/maven-api-log/src/main/java/module-info.java 
b/api/maven-api-log/src/main/java/module-info.java
new file mode 100644
index 0000000000..8dc04d31b7
--- /dev/null
+++ b/api/maven-api-log/src/main/java/module-info.java
@@ -0,0 +1,26 @@
+/*
+ * 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.
+ */
+
+module org.apache.maven.api.logging {
+    requires transitive org.apache.maven.api.annotations;
+
+    exports org.apache.maven.api.logging;
+
+    uses org.apache.maven.api.logging.LoggerManager;
+}
diff --git 
a/api/maven-api-log/src/main/java/org/apache/maven/api/logging/LogEventBuilder.java
 
b/api/maven-api-log/src/main/java/org/apache/maven/api/logging/LogEventBuilder.java
new file mode 100644
index 0000000000..250485ce58
--- /dev/null
+++ 
b/api/maven-api-log/src/main/java/org/apache/maven/api/logging/LogEventBuilder.java
@@ -0,0 +1,153 @@
+/*
+ * 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>
+ *
+ * @since 4.2.0
+ */
+@Experimental
+public interface LogEventBuilder {
+
+    /**
+     * Attaches a structured key-value pair to this log event.
+     *
+     * @param key   the key, 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.
+     *
+     * @param key   the key, 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.
+     *
+     * @param key   the key, 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).
+     *
+     * @param projectId the project id, or {@code null} to clear
+     * @return this builder
+     */
+    @Nonnull
+    LogEventBuilder withProjectId(String projectId);
+
+    /**
+     * Overrides the mojo execution identifier for this event.
+     *
+     * @param mojoId the mojo id, or {@code null} to clear
+     * @return this builder
+     */
+    @Nonnull
+    LogEventBuilder withMojoId(String mojoId);
+
+    /**
+     * Emits the log event with the given pre-formatted message.
+     *
+     * @param message the message, never {@code null}
+     */
+    void log(@Nonnull String message);
+
+    /**
+     * Emits the log event with a SLF4J-style {@code {}} template and a single 
argument.
+     * <p>
+     * Fast path that avoids varargs array allocation.
+     *
+     * @param format the message template
+     * @param arg    the single argument
+     */
+    void log(@Nonnull String format, Object arg);
+
+    /**
+     * Emits the log event with a SLF4J-style {@code {}} template and two 
arguments.
+     * <p>
+     * Fast path that avoids varargs array allocation.
+     *
+     * @param format the message template
+     * @param arg1   the first argument
+     * @param arg2   the second argument
+     */
+    void log(@Nonnull String format, Object arg1, Object arg2);
+
+    /**
+     * Emits the log event with a SLF4J-style {@code {}} template and any 
number of arguments.
+     *
+     * @param format the message template
+     * @param args   the arguments
+     */
+    void log(@Nonnull String format, Object... args);
+
+    /**
+     * Emits the log event with a lazily-evaluated message supplier.
+     * <p>
+     * The supplier is only invoked when the level is enabled. When this 
builder
+     * is a NOP instance the supplier is never called.
+     *
+     * @param messageSupplier a supplier of the log message, never {@code null}
+     */
+    void log(@Nonnull java.util.function.Supplier<String> messageSupplier);
+}
diff --git 
a/api/maven-api-log/src/main/java/org/apache/maven/api/logging/LogLevel.java 
b/api/maven-api-log/src/main/java/org/apache/maven/api/logging/LogLevel.java
new file mode 100644
index 0000000000..5620dc45a3
--- /dev/null
+++ b/api/maven-api-log/src/main/java/org/apache/maven/api/logging/LogLevel.java
@@ -0,0 +1,42 @@
+/*
+ * 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.Immutable;
+
+/**
+ * Log severity levels.
+ *
+ * @since 4.2.0
+ */
+@Experimental
+@Immutable
+public enum LogLevel {
+    /** Finest-grained diagnostic events; only useful during deep debugging. */
+    TRACE,
+    /** Diagnostic events useful during development and troubleshooting. */
+    DEBUG,
+    /** Informational messages about normal operation. */
+    INFO,
+    /** Potentially harmful situations that should be investigated. */
+    WARN,
+    /** Error events that may still allow the build to continue. */
+    ERROR
+}
diff --git 
a/api/maven-api-log/src/main/java/org/apache/maven/api/logging/Logger.java 
b/api/maven-api-log/src/main/java/org/apache/maven/api/logging/Logger.java
new file mode 100644
index 0000000000..58f43a5bda
--- /dev/null
+++ b/api/maven-api-log/src/main/java/org/apache/maven/api/logging/Logger.java
@@ -0,0 +1,393 @@
+/*
+ * 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.
+ *
+ * <h2>Fluent API (preferred)</h2>
+ * <pre>{@code
+ * log.atInfo()
+ *    .withKeyValue("artifact", artifact.getId())
+ *    .log("Resolved {} files", count);
+ * }</pre>
+ *
+ * <h2>Legacy convenience methods</h2>
+ * <pre>{@code
+ * log.info("Compiling {} source files", count);
+ * log.warn("Deprecated configuration key: {}", key, e);
+ * }</pre>
+ *
+ * @since 4.2.0
+ */
+@Experimental
+@Provider
+public interface Logger {
+
+    /**
+     * The name of this logger, typically the fully qualified class name of
+     * the component that owns it.
+     *
+     * @return the logger name, never {@code null}
+     */
+    @Nonnull
+    String name();
+
+    /**
+     * Returns {@code true} if the given level is enabled for this logger.
+     *
+     * @param level the level to test, never {@code null}
+     * @return {@code true} if enabled
+     */
+    boolean isEnabled(@Nonnull LogLevel level);
+
+    /** @return {@code true} if {@link LogLevel#TRACE} is enabled */
+    default boolean isTraceEnabled() {
+        return isEnabled(LogLevel.TRACE);
+    }
+
+    /** @return {@code true} if {@link LogLevel#DEBUG} is enabled */
+    default boolean isDebugEnabled() {
+        return isEnabled(LogLevel.DEBUG);
+    }
+
+    /** @return {@code true} if {@link LogLevel#INFO} is enabled */
+    default boolean isInfoEnabled() {
+        return isEnabled(LogLevel.INFO);
+    }
+
+    /** @return {@code true} if {@link LogLevel#WARN} is enabled */
+    default boolean isWarnEnabled() {
+        return isEnabled(LogLevel.WARN);
+    }
+
+    /** @return {@code true} if {@link LogLevel#ERROR} is enabled */
+    default boolean isErrorEnabled() {
+        return isEnabled(LogLevel.ERROR);
+    }
+
+    // ---- Fluent entry points ----
+
+    /**
+     * Returns a {@link LogEventBuilder} for {@link LogLevel#TRACE}.
+     * <p>
+     * When TRACE is disabled, returns a singleton no-op builder (zero 
allocations).
+     *
+     * @return a log builder, never {@code null}
+     */
+    @Nonnull
+    LogEventBuilder atTrace();
+
+    /**
+     * Returns a {@link LogEventBuilder} for {@link LogLevel#DEBUG}.
+     *
+     * @return a log builder, never {@code null}
+     */
+    @Nonnull
+    LogEventBuilder atDebug();
+
+    /**
+     * Returns a {@link LogEventBuilder} for {@link LogLevel#INFO}.
+     *
+     * @return a log builder, never {@code null}
+     */
+    @Nonnull
+    LogEventBuilder atInfo();
+
+    /**
+     * Returns a {@link LogEventBuilder} for {@link LogLevel#WARN}.
+     *
+     * @return a log builder, never {@code null}
+     */
+    @Nonnull
+    LogEventBuilder atWarn();
+
+    /**
+     * Returns a {@link LogEventBuilder} for {@link LogLevel#ERROR}.
+     *
+     * @return a log builder, never {@code null}
+     */
+    @Nonnull
+    LogEventBuilder atError();
+
+    /**
+     * Returns a {@link LogEventBuilder} for the given level.
+     *
+     * @param level the target level, never {@code null}
+     * @return a log builder, never {@code null}
+     */
+    @Nonnull
+    LogEventBuilder at(@Nonnull LogLevel level);
+
+    // ---- Legacy convenience: trace ----
+
+    /** Logs a TRACE message. */
+    default void trace(@Nonnull String message) {
+        atTrace().log(message);
+    }
+
+    /** Logs a TRACE message with one {@code {}} argument. */
+    default void trace(@Nonnull String format, @Nullable Object arg) {
+        atTrace().log(format, arg);
+    }
+
+    /** Logs a TRACE message with two {@code {}} arguments. */
+    default void trace(@Nonnull String format, @Nullable Object arg1, 
@Nullable Object arg2) {
+        atTrace().log(format, arg1, arg2);
+    }
+
+    /** Logs a TRACE message with varargs arguments. */
+    default void trace(@Nonnull String format, Object... args) {
+        atTrace().log(format, args);
+    }
+
+    /** Logs a TRACE message with a throwable. */
+    default void trace(@Nonnull String message, @Nullable Throwable t) {
+        atTrace().withThrowable(t).log(message);
+    }
+
+    /** Logs a lazily-evaluated TRACE message. */
+    default void trace(@Nonnull Supplier<String> message) {
+        atTrace().log(message);
+    }
+
+    /** Logs a lazily-evaluated TRACE message with a throwable. */
+    default void trace(@Nonnull Supplier<String> message, @Nullable Throwable 
t) {
+        atTrace().withThrowable(t).log(message);
+    }
+
+    // ---- Legacy convenience: debug ----
+
+    /** Logs a DEBUG message. */
+    default void debug(@Nonnull String message) {
+        atDebug().log(message);
+    }
+
+    /** Logs a DEBUG message with one {@code {}} argument. */
+    default void debug(@Nonnull String format, @Nullable Object arg) {
+        atDebug().log(format, arg);
+    }
+
+    /** Logs a DEBUG message with two {@code {}} arguments. */
+    default void debug(@Nonnull String format, @Nullable Object arg1, 
@Nullable Object arg2) {
+        atDebug().log(format, arg1, arg2);
+    }
+
+    /** Logs a DEBUG message with varargs arguments. */
+    default void debug(@Nonnull String format, Object... args) {
+        atDebug().log(format, args);
+    }
+
+    /** Logs a DEBUG message with a throwable. */
+    default void debug(@Nonnull String message, @Nullable Throwable t) {
+        atDebug().withThrowable(t).log(message);
+    }
+
+    /** Logs a lazily-evaluated DEBUG message. */
+    default void debug(@Nonnull Supplier<String> message) {
+        atDebug().log(message);
+    }
+
+    /** Logs a lazily-evaluated DEBUG message with a throwable. */
+    default void debug(@Nonnull Supplier<String> message, @Nullable Throwable 
t) {
+        atDebug().withThrowable(t).log(message);
+    }
+
+    // ---- Legacy convenience: info ----
+
+    /** Logs an INFO message. */
+    default void info(@Nonnull String message) {
+        atInfo().log(message);
+    }
+
+    /** Logs an INFO message with one {@code {}} argument. */
+    default void info(@Nonnull String format, @Nullable Object arg) {
+        atInfo().log(format, arg);
+    }
+
+    /** Logs an INFO message with two {@code {}} arguments. */
+    default void info(@Nonnull String format, @Nullable Object arg1, @Nullable 
Object arg2) {
+        atInfo().log(format, arg1, arg2);
+    }
+
+    /** Logs an INFO message with varargs arguments. */
+    default void info(@Nonnull String format, Object... args) {
+        atInfo().log(format, args);
+    }
+
+    /** Logs an INFO message with a throwable. */
+    default void info(@Nonnull String message, @Nullable Throwable t) {
+        atInfo().withThrowable(t).log(message);
+    }
+
+    /** Logs a lazily-evaluated INFO message. */
+    default void info(@Nonnull Supplier<String> message) {
+        atInfo().log(message);
+    }
+
+    /** Logs a lazily-evaluated INFO message with a throwable. */
+    default void info(@Nonnull Supplier<String> message, @Nullable Throwable 
t) {
+        atInfo().withThrowable(t).log(message);
+    }
+
+    // ---- Legacy convenience: warn ----
+
+    /** Logs a WARN message. */
+    default void warn(@Nonnull String message) {
+        atWarn().log(message);
+    }
+
+    /** Logs a WARN message with one {@code {}} argument. */
+    default void warn(@Nonnull String format, @Nullable Object arg) {
+        atWarn().log(format, arg);
+    }
+
+    /** Logs a WARN message with two {@code {}} arguments. */
+    default void warn(@Nonnull String format, @Nullable Object arg1, @Nullable 
Object arg2) {
+        atWarn().log(format, arg1, arg2);
+    }
+
+    /** Logs a WARN message with varargs arguments. */
+    default void warn(@Nonnull String format, Object... args) {
+        atWarn().log(format, args);
+    }
+
+    /** Logs a WARN message with a throwable. */
+    default void warn(@Nonnull String message, @Nullable Throwable t) {
+        atWarn().withThrowable(t).log(message);
+    }
+
+    /** Logs a lazily-evaluated WARN message. */
+    default void warn(@Nonnull Supplier<String> message) {
+        atWarn().log(message);
+    }
+
+    /** Logs a lazily-evaluated WARN message with a throwable. */
+    default void warn(@Nonnull Supplier<String> message, @Nullable Throwable 
t) {
+        atWarn().withThrowable(t).log(message);
+    }
+
+    // ---- Legacy convenience: error ----
+
+    /** Logs an ERROR message. */
+    default void error(@Nonnull String message) {
+        atError().log(message);
+    }
+
+    /** Logs an ERROR message with one {@code {}} argument. */
+    default void error(@Nonnull String format, @Nullable Object arg) {
+        atError().log(format, arg);
+    }
+
+    /** Logs an ERROR message with two {@code {}} arguments. */
+    default void error(@Nonnull String format, @Nullable Object arg1, 
@Nullable Object arg2) {
+        atError().log(format, arg1, arg2);
+    }
+
+    /** Logs an ERROR message with varargs arguments. */
+    default void error(@Nonnull String format, Object... args) {
+        atError().log(format, args);
+    }
+
+    /** Logs an ERROR message with a throwable. */
+    default void error(@Nonnull String message, @Nullable Throwable t) {
+        atError().withThrowable(t).log(message);
+    }
+
+    /** Logs a lazily-evaluated ERROR message. */
+    default void error(@Nonnull Supplier<String> message) {
+        atError().log(message);
+    }
+
+    /** Logs a lazily-evaluated ERROR message with a throwable. */
+    default void error(@Nonnull Supplier<String> message, @Nullable Throwable 
t) {
+        atError().withThrowable(t).log(message);
+    }
+
+    // ---- Static factory ----
+
+    /**
+     * Returns a {@code Logger} for the given class, using the fully-qualified
+     * class name as the logger name.
+     * <p>
+     * Shorthand for {@code LoggerManager.get().getLogger(clazz)}.
+     * Safe to call at any point — even during early bootstrap before the
+     * real logging implementation is available. In that case, a bootstrap
+     * logger is returned that buffers events until the real implementation
+     * is discovered.
+     *
+     * @param clazz the class whose name is used as the logger name, never 
{@code null}
+     * @return a {@code Logger} instance, never {@code null}
+     * @since 4.2.0
+     */
+    @Nonnull
+    static Logger of(@Nonnull Class<?> clazz) {
+        return LoggerManager.get().getLogger(clazz);
+    }
+
+    /**
+     * Returns a {@code Logger} with the given name.
+     * <p>
+     * Shorthand for {@code LoggerManager.get().getLogger(name)}. Intended for
+     * framework code or dynamic logger names.
+     * Safe to call at any point — even during early bootstrap.
+     *
+     * @param name the logger name, never {@code null}
+     * @return a {@code Logger} instance, never {@code null}
+     * @since 4.2.0
+     */
+    @Nonnull
+    static Logger of(@Nonnull String name) {
+        return LoggerManager.get().getLogger(name);
+    }
+
+    // ---- Child logger ----
+
+    /**
+     * Returns a child logger whose name is this logger's name with
+     * {@code "." + name} appended.
+     *
+     * <p>If this logger was constructed with a {@code projectId} and/or 
{@code mojoId}
+     * (as is the case for DI-injected mojo loggers), those values are 
propagated to the
+     * child so sub-component events are automatically tagged with the correct 
project and
+     * mojo execution. Loggers obtained via {@link #of(Class)} or {@link 
#of(String)} have
+     * no such context, and the child will likewise carry {@code null} for 
those fields.</p>
+     *
+     * @param name the child suffix, never {@code null}
+     * @return a child {@code Logger} instance, never {@code null}
+     */
+    @Nonnull
+    Logger child(@Nonnull String name);
+}
diff --git 
a/api/maven-api-log/src/main/java/org/apache/maven/api/logging/package-info.java
 
b/api/maven-api-log/src/main/java/org/apache/maven/api/logging/package-info.java
new file mode 100644
index 0000000000..8ad23889b6
--- /dev/null
+++ 
b/api/maven-api-log/src/main/java/org/apache/maven/api/logging/package-info.java
@@ -0,0 +1,122 @@
+/*
+ * 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.
+ */
+
+/**
+ * Maven unified logging API — a first-class, SLF4J-free logging facade for
+ * plugins, extensions, and Maven internals.
+ *
+ * <h2>Overview</h2>
+ * <p>
+ * This package replaces the older {@code org.apache.maven.api.plugin.Log}
+ * plugin facade and the SLF4J-backed CLI logger with a single, consistent
+ * API that works uniformly across mojos, extensions, and Maven's own
+ * internal components.
+ * </p>
+ *
+ * <h2>Core types</h2>
+ * <dl>
+ *   <dt>{@link org.apache.maven.api.logging.Logger}</dt>
+ *   <dd>The primary logging interface. Obtained via {@link 
org.apache.maven.api.logging.Logger#of(Class)}
+ *   or injected by the container. Supports a fluent builder API ({@code 
atInfo()…log(…)})
+ *   as well as SLF4J-style convenience methods ({@code info(…)}, {@code 
warn(…)}, etc.).
+ *   Instances are safe to hold in static or instance fields — context such as
+ *   {@code projectId} and {@code mojoId} is resolved from a per-thread
+ *   {@link org.apache.maven.api.logging.LogSink} at dispatch time.</dd>
+ *
+ *   <dt>{@link org.apache.maven.api.logging.LogEventBuilder}</dt>
+ *   <dd>Fluent builder for a single log event. Obtained from {@code 
Logger.atLevel()}.
+ *   Accumulates level, message template, arguments, throwable, and key-value 
pairs
+ *   before dispatching via {@code log(…)}. When the target level is disabled, 
returns
+ *   a no-op singleton (zero allocations).</dd>
+ *
+ *   <dt>{@link org.apache.maven.api.logging.LogEvent}</dt>
+ *   <dd>Immutable record of a single log event. Carries the logger name, 
level, raw
+ *   message template, arguments (lazy formatting), throwable, and optional
+ *   {@code projectId} / {@code mojoId} context. Passed to {@link 
org.apache.maven.api.logging.LogSink}
+ *   for consumption.</dd>
+ *
+ *   <dt>{@link org.apache.maven.api.logging.LogSink}</dt>
+ *   <dd>Consumer of {@link org.apache.maven.api.logging.LogEvent}s. This is 
the primary
+ *   extension point for embedders and build tools: implement {@code LogSink} 
and register
+ *   it via {@link 
org.apache.maven.api.logging.LoggerManager#setLogSink(LogSink)} (or via
+ *   {@link java.util.ServiceLoader} discovery) to redirect all Maven log 
output to any
+ *   destination — a UI, a structured log store, a test buffer, etc.</dd>
+ *
+ *   <dt>{@link org.apache.maven.api.logging.LoggerManager}</dt>
+ *   <dd>Central control surface: obtains loggers, installs the active sink, 
configures
+ *   root and per-logger levels, and tracks the highest severity reached (for
+ *   {@code --fail-on-severity}). Accessed via {@link 
org.apache.maven.api.logging.LoggerManager#get()},
+ *   which is set up by Maven before any logging occurs.</dd>
+ *
+ *   <dt>{@link org.apache.maven.api.logging.LogLevel}</dt>
+ *   <dd>Ordered severity enumeration: {@code TRACE}, {@code DEBUG}, {@code 
INFO},
+ *   {@code WARN}, {@code ERROR}.</dd>
+ * </dl>
+ *
+ * <h2>Getting a logger</h2>
+ * <p>
+ * The typical pattern for plugin and extension code is:
+ * </p>
+ * <pre>{@code
+ * private final Logger log = Logger.of(MyComponent.class);
+ * }</pre>
+ * <p>
+ * {@code Logger.of()} is safe to call at any point, even during early 
bootstrap
+ * before the real logging implementation is available. In that case a 
bootstrap
+ * logger is returned that buffers events until the real implementation is
+ * discovered via {@link java.util.ServiceLoader} or installed via
+ * {@link org.apache.maven.api.logging.LoggerManager#set(LoggerManager)}.
+ * </p>
+ * <p>
+ * Framework code that does not have a class reference can use the string 
overload:
+ * </p>
+ * <pre>{@code
+ * Logger log = Logger.of("org.apache.maven.my-component");
+ * }</pre>
+ *
+ * <h2>Logging events</h2>
+ * <p>Fluent API (preferred — enables lazy formatting and structured key-value 
pairs):</p>
+ * <pre>{@code
+ * log.atInfo()
+ *    .withKeyValue("artifact", artifact.getId())
+ *    .log("Resolved {} files", count);
+ * }</pre>
+ * <p>Convenience methods (SLF4J-style shorthand):</p>
+ * <pre>{@code
+ * log.info("Compiling {} source files", count);
+ * log.warn("Deprecated key: {}", key, e);
+ * }</pre>
+ *
+ * <h2>Embedder integration</h2>
+ * <p>
+ * To redirect Maven log output, implement {@link 
org.apache.maven.api.logging.LogSink}
+ * and either:
+ * </p>
+ * <ul>
+ *   <li>Register it via {@code ServiceLoader} — place a
+ *       {@code META-INF/services/org.apache.maven.api.logging.LogSink} file 
on the
+ *       classpath pointing to your implementation. Maven discovers it before 
any
+ *       logging occurs.</li>
+ *   <li>Or call {@link 
org.apache.maven.api.logging.LoggerManager#setLogSink(LogSink)}
+ *       programmatically during embedder setup.</li>
+ * </ul>
+ *
+ * @since 4.2.0
+ */
+package org.apache.maven.api.logging;

Reply via email to