Fix broken links (mostly JavaDoc and Log4j API)

Part of #2491

log4j-plugins/pom.xml

@@ -30,6 +30,8 @@
   <description>Log4j Plugin Support</description>
 
   <properties>
+    <maven.javadoc.skip>false</maven.javadoc.skip>
+
     <bnd-extra-package-options>
       <!-- External optional dependencies -->
       com.google.errorprone.annotations.concurrent;resolution:=optional,

log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/condition/Condition.java

@@ -20,9 +20,10 @@
 
 /**
  * Checks an annotated element to see if it matches some condition.
- *
- * @implSpec Must have a default constructor. The class should be used in a {@link Conditional} annotation on an
- * annotation class to provide parameters to the condition.
+ * <p>
+ * <strong>Implementation note:</strong> must have a default constructor. The class should be used in a
+ * {@link Conditional} annotation on an annotation class to provide parameters to the condition.
+ * </p>
  */
 @FunctionalInterface
 public interface Condition {

log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/convert/TypeConverter.java

@@ -22,9 +22,12 @@
 
 /**
  * Interface for doing automatic String conversion to a specific type.
+ * <p>
+ * <strong>Implementation note:</strong> type converter plugins must be annotated with {@link Plugin} and
+ * {@link TypeConverters}.
+ * </p>
  *
  * @param <T> Converts Strings into the given type {@code T}.
- * @implSpec Type converter plugins must be annotated with {@link Plugin} and {@link TypeConverters}.
  * @since 3.0.0 Moved to {@code log4j-plugins}.
  */
 @FunctionalInterface

log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Key.java

@@ -122,8 +122,9 @@ public final Class<T> getRawType() {
 
     /**
      * Returns the name of this key. If this key has no defined name, then this returns an empty string.
-     *
-     * @apiNote Names are case-preserving but should be compared using case-insensitive string comparison.
+     * <p>
+     *     <strong>API note:</strong> names are case-preserving but should be compared using case-insensitive string comparison.
+     * </p>
      * @see Keys#hasName(AnnotatedElement)
      */
     public final String getName() {
@@ -132,8 +133,9 @@ public final String getName() {
 
     /**
      * Returns the namespace of this key. If this key has no defined namespace, then this returns an empty string.
-     *
-     * @apiNote A namespace of the empty string is considered the default namespace which is used when no
+     * <p>
+     *     <strong>API note:</strong> a namespace of the empty string is considered the default namespace which is used when no namespace is defined or if the namespace is explicitly defined as the empty string.
+     * </p>
      * namespace is defined or if the namespace is explicitly defined as the empty string.
      * @see Keys#getNamespace(AnnotatedElement)
      */

log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/resolver/package-info.java

@@ -20,7 +20,7 @@
  * org.apache.logging.log4j.plugins.di.spi.FactoryResolver#supportsKey(org.apache.logging.log4j.plugins.di.Key)
  * supported keys} from {@linkplain org.apache.logging.log4j.plugins.di.ConfigurableInstanceFactory existing instance
  * factories}. Resolvers should be
- * {@linkplain org.apache.logging.log4j.plugins.di.ConfigurableInstanceFactory#registerFactoryResolver(FactoryResolver<T>)
+ * {@linkplain org.apache.logging.log4j.plugins.di.ConfigurableInstanceFactory#registerFactoryResolver(org.apache.logging.log4j.plugins.di.spi.FactoryResolver)}
  * registered} via a {@link org.apache.logging.log4j.plugins.di.spi.ConfigurableInstanceFactoryPostProcessor
  * ConfigurableInstanceFactoryPostProcessor} service.
  */
@@ -29,7 +29,6 @@
 @NullMarked
 package org.apache.logging.log4j.plugins.di.resolver;
 
-import org.apache.logging.log4j.plugins.di.spi.FactoryResolver;
 import org.jspecify.annotations.NullMarked;
 import org.osgi.annotation.bundle.Export;
 import org.osgi.annotation.versioning.Version;

src/site/antora/modules/ROOT/pages/javadoc.adoc

@@ -27,6 +27,9 @@ The table below contains links to the Javadoc API Documentation for the componen
 |link:javadoc/log4j-kit/index.html[Implementation helper kit]
 |Common helper functions for Log4j API implementations.
 
+|link:javadoc/log4j-plugins/index.html[Dependency injection kit]
+|Dependency injection artifact used in Log4j 3 Core.
+
 |link:javadoc/log4j-core/index.html[Reference implementation]
 |The standard implementation, also called the Log4j 3 Core, that contains Appenders, Filters, and more.
 

src/site/antora/modules/ROOT/pages/log4j-iostreams.adoc

@@ -23,7 +23,7 @@ xref:manual/api.adoc[]
 extension that provides numerous classes from
 http://docs.oracle.com/javase/{java-target-version}/docs/api/java/io/package-summary.html[`java.io`]
 that can either write to a
-link:javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`]
+{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`]
 while writing to another `OutputStream` or `Writer`, or the contents read by an `InputStream` or `Reader` can be http://www.eaipatterns.com/WireTap.html[wiretapped] by a `Logger`.
 
 == Requirements

src/site/antora/modules/ROOT/pages/log4j-jul.adoc

@@ -66,31 +66,31 @@ Using the default `LevelConverter` implementation, custom logging levels are map
 | Java Level | Log4j Level
 
 | http://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Level.html#OFF[OFF]
-| link:../javadoc/log4j-api/org/apache/logging/log4j/Level#OFF[OFF]
+| {log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/Level.html#OFF[OFF]
 
 | http://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Level.html#SEVERE[SEVERE]
-| link:../javadoc/log4j-api/org/apache/logging/log4j/Level#ERROR[ERROR]
+| {log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/Level.html#ERROR[ERROR]
 
 | http://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Level.html#WARNING[WARNING]
-| link:../javadoc/log4j-api/org/apache/logging/log4j/Level#WARN[WARN]
+| {log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/Level.html#WARN[WARN]
 
 | http://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Level.html#OFF[OFF]
-| link:../javadoc/log4j-api/org/apache/logging/log4j/Level#INFO[INFO]
+| {log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/Level.html#INFO[INFO]
 
 | http://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Level.html#CONFIG[CONFIG]
 | custom `CONFIG` level
 
 | http://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Level.html#FINE[FINE]
-| link:../javadoc/log4j-api/org/apache/logging/log4j/Level#DEBUG[DEBUG]
+| {log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/Level.html#DEBUG[DEBUG]
 
 | http://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Level.html#FINER[FINER]
-| link:../javadoc/log4j-api/org/apache/logging/log4j/Level#TRACE[TRACE]
+| {log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/Level.html#TRACE[TRACE]
 
 | http://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Level.html#FINEST[FINEST]
 | custom `FINEST` level
 
 | http://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Level.html#ALL[ALL]
-| link:../javadoc/log4j-api/org/apache/logging/log4j/Level#ALL[ALL]
+| {log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/Level.html#ALL[ALL]
 |===
 
 == Log4j JDK Logging Bridge Handler

src/site/antora/modules/ROOT/pages/manual/appenders.adoc

@@ -775,11 +775,11 @@ list of column mapping configurations. Each column must specify a column
 name. Each column can have a conversion type specified by its fully
 qualified class name. By default, the conversion type is `String`. If
 the configured type is assignment-compatible with
-link:../javadoc/log4j-api/org/apache/logging/log4j/util/ReadOnlyStringMap.html[`ReadOnlyStringMap`]
+{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/util/ReadOnlyStringMap.html[`ReadOnlyStringMap`]
 /
-link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap.html[`ThreadContextMap`]
+{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap.html[`ThreadContextMap`]
 or
-link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextStack.html[`ThreadContextStack`],
+{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextStack.html[`ThreadContextStack`],
 then that column will be populated with the MDC or NDC respectively
 (this is database-specific how they handle inserting a `Map` or `List`
 value). If the configured type is assignment-compatible with

src/site/antora/modules/ROOT/pages/manual/async.adoc

@@ -69,10 +69,10 @@ This is the simplest to configure and gives the best performance: to make all lo
 xref:manual/systemproperties.adoc#log4j.loggerContext.selector[`log4j.loggerContext.selector`]
 property to one of the asynchronous logger context selectors:
 
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/BasicAsyncLoggerContextSelector.html[org.apache.logging.log4j.core.async.BasicAsyncLoggerContextSelector]::
+link:../javadoc/log4j-async-logger/org/apache/logging/log4j/async/logger/BasicAsyncLoggerContextSelector.html[org.apache.logging.log4j.core.async.BasicAsyncLoggerContextSelector]::
 This will create a single logger context and disruptor for all the classes in the JVM,
 
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncLoggerContextSelector.html[org.apache.logging.log4j.core.async.AsyncLoggerContextSelector]::
+link:../javadoc/log4j-async-logger/org/apache/logging/log4j/async/logger/AsyncLoggerContextSelector.html[org.apache.logging.log4j.core.async.AsyncLoggerContextSelector]::
 This will create a different logger context and disruptor for each classloader in the JVM.
 
 [IMPORTANT]
@@ -157,7 +157,7 @@ In order to use a custom wait strategy you need to:
 
 . Use the <<MixedSync-Async,mixed sync/async configuration method>> above,
 . Implement the interface
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncWaitStrategyFactory.html[AsyncWaitStrategyFactory]; the implementation must have a public no-arg constructor,
+link:../javadoc/log4j-async-logger/org/apache/logging/log4j/async/logger/AsyncWaitStrategyFactory.html[AsyncWaitStrategyFactory]; the implementation must have a public no-arg constructor,
 . Add an xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-async-AsyncWaitStrategyFactoryConfig[AsyncWaitStrategyFactory Log4j plugin]
 to your configuration.
 

src/site/antora/modules/ROOT/pages/manual/configuration.adoc

@@ -119,7 +119,7 @@ The Log4j runtime is composed of xref:manual/plugins.adoc[plugins], which are li
 Appenders, layouts, filters, configuration loaders, and similar components are all accessed as plugins.
 
 All configuration files are represented internally as a tree of
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/Node.html[Node]s,
+``link:../javadoc/log4j-plugins/org/apache/logging/log4j/plugins/Node.html[Node]``s,
 which is translated into a tree of Log4j plugins.
 The tree's root creates a
 link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration.html[Configuration]
@@ -419,13 +419,13 @@ To modify these options during a reconfiguration, you also need to change the re
 [cols="1h,5"]
 |===
 | Type
-| link:../javadoc/log4j-api/org/apache/logging/log4j/Level.html[LEVEL]
+| {log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/Level.html[LEVEL]
 
 | Status
 | **DEPRECATED**
 
 | Default value
-| link:../../2.x/manual/systemproperties.html#log4j.sta.statusLoggerLevel[log4j2.statusLoggerLevel]
+| {log4j2-url}/manual/systemproperties.html#log4j.statusLoggerLevel[log4j2.statusLoggerLevel]
 |===
 
 Overrides the logging level of the status logger.
@@ -464,7 +464,7 @@ There **must** be at least a `Root` or `AsyncRoot` element in every configuratio
 Other logger configurations are optional.
 
 Every
-link:../javadoc/log4j-api/org/apache/logging/log4j/Logger.html[Logger]
+{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/Logger.html[Logger]
 in your application is assigned to one of these logger configurations (see
 xref:manual/architecture.adoc#loggerconfig[architecture]), which determines the events that will be logged and those that won't.
 
@@ -587,7 +587,7 @@ xref:manual/architecture.adoc#logger-hierarchy[parent logger]).
 [cols="1h,5"]
 |===
 | Type
-| link:../javadoc/log4j-api/org/apache/logging/log4j/Level.html[Level]
+| {log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/Level.html[Level]
 
 | Default value
 a|
@@ -714,7 +714,8 @@ Specifies the name of the appender to use.
 
 [cols="1h,5"]
 |===
-| Type          | link:../javadoc/log4j-api/org/apache/logging/log4j/Level.html[Level]
+| Type
+| {log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/Level.html[Level]
 |===
 
 Specifies the level threshold that a log event must have to be logged.

src/site/antora/modules/ROOT/pages/manual/extending.adoc

@@ -47,10 +47,13 @@ Applications may change the LoggerContextFactory that will be used by
 
 1.  Create a binding to the logging implementation.
 ..  Implement a new link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/Log4jContextFactory.html[`LoggerContextFactory`].
-..  Implement a class that extends link:../javadoc/log4j-core/org/apache/logging/spi/Provider.html[`org.apache.logging.spi.Provider`]
+..  Implement a class that extends
+{log4j2-url}/javadoc/log4j-api/org/apache/logging/spi/Provider.html[`org.apache.logging.spi.Provider`]
 with a no-arg constructor that calls super-class's constructor with the
 Priority, the API version(s), `LoggerContextFactory` class, and
-optionally, a link:../javadoc/log4j-core/org/apache/logging/log4j/spi/ThreadContextMap.html[`ThreadContextMap`] implementation class.
+optionally, a
+{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap.html[`ThreadContextMap`]
+implementation class.
 ..  Create a `META-INF/services/org.apache.logging.spi.Provider` file
 that contains the name of the class that implements
 `org.apache.logging.spi.Provider`.
@@ -76,8 +79,7 @@ Callback classes must have a no-args constructor and need to be defined in two p
 == ContextSelector
 
 ContextSelectors are called by the
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/Log4jContextFactory.html[Log4j
-LoggerContext factory]. They perform the actual work of locating or
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/Log4jContextFactory.html[Log4j LoggerContext factory]. They perform the actual work of locating or
 creating a LoggerContext, which is the anchor for Loggers and their
 configuration. ContextSelectors are free to implement any mechanism they
 desire to manage LoggerContexts. The default Log4jContextFactory checks

src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc

@@ -269,7 +269,7 @@ Logging more than 10 parameters creates https://docs.oracle.com/javase/8/docs/te
 
 When a message parameter contains an unknown type by the layout, it will encode by calling `toString()` on these objects.
 Most objects don't have garbage-free `toString()` methods.
-Objects themselves can implement their own garbage-free encoders by either extending from https://docs.oracle.com/javase/8/docs/api/java/lang/CharSequence.html[Java's `CharSequence`] or link:../javadoc/log4j-api/org/apache/logging/log4j/util/StringBuilderFormattable.html[Log4j's `StringBuilderFormattable`].
+Objects themselves can implement their own garbage-free encoders by either extending from https://docs.oracle.com/javase/8/docs/api/java/lang/CharSequence.html[Java's `CharSequence`] or {log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/util/StringBuilderFormattable.html[Log4j's `StringBuilderFormattable`].
 
 [#codeImpact]
 === Avoiding autoboxing

src/site/antora/modules/ROOT/pages/manual/layouts.adoc

@@ -904,7 +904,7 @@ The STYLE value can be one of:
 *map*\{key} +
 *MAP*\{key}
 |Outputs the entries in a
-link:../javadoc/log4j-api/org/apache/logging/log4j/message/MapMessage.html[MapMessage],
+{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/message/MapMessage.html[MapMessage],
 if one is present in the event. The `K` conversion character can be
 followed by the key for the map placed between braces, as in
 `%K\{clientNumber}` where `clientNumber` is the key. The value of the Map
@@ -1294,7 +1294,7 @@ set is output using a format {key1=val1, key2=val2}.
 The key/value pairs will be printed in sorted order.
 
 See the
-link:../javadoc/log4j-api/org/apache/logging/log4j/ThreadContext.html[ThreadContext]
+{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/ThreadContext.html[ThreadContext]
 class for more details.
 
 |[[PatternUUID]] *u*{"RANDOM" \| "TIME"} +
@@ -1655,7 +1655,7 @@ resulting from evaluation of the pattern - garbage-free since 2.8
 
 |%K\{key}, %map\{key}, %MAP\{key}
 |Outputs the entries in a
-link:../javadoc/log4j-api/org/apache/logging/log4j/message/MapMessage.html[MapMessage],
+{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/message/MapMessage.html[MapMessage],
 if one is present in the event - garbage-free since 2.8.
 
 |%m, %msg, %message

src/site/antora/modules/ROOT/partials/manual/api-intro.adoc

@@ -15,7 +15,7 @@
     limitations under the License.
 ////
 
-To write logs, you need a link:../javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`] instance which you will retrieve from the link:../javadoc/log4j-api/org/apache/logging/log4j/LogManager.html[`LogManager`].
+To write logs, you need a {log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`] instance which you will retrieve from the {log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/LogManager.html[`LogManager`].
 You can use the `Logger` instance to write logs by using methods like `info()`, `warn()`, `error()`, etc.
 These methods are named after the _log levels_ they represent, a way to categorize log events by severity.
 The log message can also contain placeholders written as `{}` that will be replaced by the arguments passed to the method.

src/site/antora/modules/ROOT/partials/manual/async-trade-offs.adoc

@@ -29,7 +29,7 @@ It can prevent or dampen latency spikes by shortening the wait time until the ne
 If the queue size is large enough to handle the burst, asynchronous logging will prevent your application from falling behind during a sudden increase of activity.
 
 Lower logging latency::
-link:../javadoc/log4j-api/org/apache/logging/log4j/Logger.html[Logger]
+{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/Logger.html[Logger]
 method calls return faster, since most of the work is done on the I/O thread.
 
 [#async-drawbacks]
@@ -54,7 +54,7 @@ xref:manual/async.adoc#MixedSync-Async[mixed synchronous/asynchronous loggers] o
 
 Stateful messages::
 Most
-link:../javadoc/log4j-api/org/apache/logging/log4j/message/Message.html[`Message`]
+{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/message/Message.html[`Message`]
 implementations take a snapshot of the formatted message on the calling thread (cf.
 xref:manual/systemproperties.adoc#log4j.async.formatMessagesInBackground[`log4j.async.formatMessagesInBackground`]).
 The log message will not change even if the arguments of the logging call are modified later.
@@ -67,9 +67,9 @@ for example are mutable by design: fields can be added to these messages after t
 These messages should not be modified after they are logged with asynchronous loggers or asynchronous appenders.
 +
 Similarly, custom
-link:../javadoc/log4j-api/org/apache/logging/log4j/message/Message.html[`Message`]
+{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/message/Message.html[`Message`]
 implementations should be designed with asynchronous use in mind, and either take a snapshot of their parameters at construction time, or document their thread-safety characteristics (see
-link:../javadoc/log4j-api/org/apache/logging/log4j/message/AsynchronouslyFormattable.html[`AsynchronouslyFormattable`]).
+{log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/message/AsynchronouslyFormattable.html[`AsynchronouslyFormattable`]).
 
 Computational overhead::
 If your application is running in an environment where CPU resources are scarce, like a VM with a single vCPU, starting another thread is not likely to give better performance.