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;
