vpelikh commented on code in PR #4230:
URL: https://github.com/apache/logging-log4j2/pull/4230#discussion_r4148097213
##########
src/site/antora/modules/ROOT/pages/manual/extending.adoc:
##########
@@ -14,490 +14,151 @@
See the License for the specific language governing permissions and
limitations under the License.
////
-= Extending Log4j
-Log4j provides numerous ways that it can be manipulated and extended.
-This section includes an overview of the various ways that are directly
-supported by the Log4j 3 implementation.
+= Extending
+
+Log4j provides numerous extension points to adapt it for custom needs.
+Several of such extension points are covered in the page of the associated
component:
+
+* Log4j API
+** {log4j2-url}/manual/customloglevels.html[Extending levels]
+** {log4j2-url}/manual/markers.html[Extending markers]
+** {log4j2-url}/manual/messages.html#extending[Extending messages]
+** {log4j2-url}/manual/thread-context.html#extending[Extending thread context]
+* Log4j Core
+** xref:manual/appenders.adoc#extending[Extending appenders]
+** xref:manual/filters.adoc#extending[Extending filters]
+** xref:manual/layouts.adoc#extending[Extending layouts]
+*** xref:manual/json-template-layout.adoc#extending[Extending JSON Template
Layout]
+*** xref:manual/pattern-layout.adoc#extending[Extending Pattern Layout]
+** xref:manual/lookups.adoc#extending[Extending lookups]
+
+This section guides you on the rest of the Log4j extension points.
+
+[#mechanisms]
+== Extension mechanisms
+
+Log4j allows extensions primarily using following mechanisms:
+
+[#Custom_Plugins]
+=== Plugins
+
+include::partial$manual/plugin-preliminaries.adoc[]
+
+[#bindings]
+=== Bindings
+
+The Log4j plugin system was enhanced in 3.0 to support arbitrary bindings for
xref:manual/dependencyinjection.adoc[dependency injection].
+Many shared components in Log4j could be configured via system properties or
similar to include a fully qualified class name to use.
+Using custom bindings, however, these custom classes can be configured as code.
+Default bindings are configured in
{project-github-url}/log4j-core/src/main/java/org/apache/logging/log4j/core/impl/CoreDefaultBundle.java[`CoreDefaultBundle`].
+Custom bindings can be installed by defining a
link:../javadoc/log4j-plugins/org/apache/logging/log4j/plugins/di/spi/ConfigurableInstanceFactoryPostProcessor.html[`ConfigurableInstanceFactoryPostProcessor`]
service class which invokes `ConfigurableInstanceFactory::registerBundle` to
register the bundle class containing the bindings.
+This approach is more portable than the legacy approach of using system
properties to define the classes as it removes ambiguity of `ClassLoader`
ownership and other details of modules and similar runtimes.
+
+[#service-loader]
+=== ``ServiceLoader``s
+
+https://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/ServiceLoader.html[`ServiceLoader`]
is a simple service-provider loading facility baked into the Java platform
itself.
+Log4j uses ``ServiceLoader``s for extending places where
+
+* The service needs to be implementation agnostic.
+As a result, <<Custom_Plugins,the Log4j plugin system>> cannot be used, since
it is provided by the logging implementation, i.e., Log4j Core.
+For instance, this is why
{log4j2-url}/manual/thread-context.html#extending[extending Thread Context],
which is a Log4j API component, works using ``ServiceLoader``s.
+
+* The service needs to be loaded before <<Custom_Plugins,the Log4j plugin
system>>.
+For instance, this is why <<Provider,extending `Provider`>> works using
``ServiceLoader``s.
+
+Refer to
https://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/ServiceLoader.html[the
`ServiceLoader` documentation] for details.
+
+[#system-properties]
+=== System properties
+
+Log4j uses system properties to determine the fully-qualified class name
(FQCN) to load for extending a certain functionality.
+For instance, <<MessageFactory, extending `MessageFactory2`>> works using
system properties.
+
+[WARNING]
+====
+Loading a class using _only_ its FQCN can result in unexpected behaviour when
there are multiple class loaders.
+====
+
+[#points]
+== Extension points
+
+In this section we will guide you on certain Log4j extension points that are
not covered elsewhere.
+
+[#Provider]
+=== `Provider`
+
+link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider.html[`Provider`]
is the anchor contract binding Log4j API to an implementation.
+For instance, it has been implemented by Log4j Core, Log4j-to-JUL bridge, and
Log4j-to-SLF4J bridge modules.
+
+Under the hood,
link:../javadoc/log4j-api/org/apache/logging/log4j/LogManager.html[`LogManager`]
locates a `Provider` implementation using <<service-loader,the `ServiceLoader`
mechanism>>, and delegates invocations to it.
+Hence, you can extend it by providing a
`org.apache.logging.log4j.spi.Provider` implementation in the form of a
`ServiceLoader`.
+
+Having multiple ``Provider``s in the classpath is strongly discouraged.
+A specific provider can be <<bindings,bound>> using a custom bundle class if
Log4j Core is also available.
+Alternatively, you can use
xref:manual/systemproperties.adoc#log4j.provider[the `log4j.provider` property]
to explicitly select one.
Review Comment:
Updated to log4j2.provider in
[0722640](https://github.com/apache/logging-log4j2/pull/4230/commits/0722640deabef8b6c1c5d1bbcc96ba385da84ff9).
--
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]
