vy commented on code in PR #2696:
URL: https://github.com/apache/logging-log4j2/pull/2696#discussion_r1663673821
##########
src/site/antora/modules/ROOT/pages/manual/plugins.adoc:
##########
@@ -14,88 +14,274 @@
See the License for the specific language governing permissions and
limitations under the License.
////
+
= Plugins
-Log4j 1.x allowed for extension by requiring class attributes on most of the
configuration declarations. In the case of some elements, notably the
PatternLayout, the only way to add new pattern converters was to extend the
PatternLayout class and add them via code. One goal of Log4j 2 is to make
extending it extremely easy through the use of plugins.
+Log4j plugin system is the de facto extension mechanism embraced by various
Log4j Core components.
+Plugins make it possible for extensible components to _receive_ feature
implementations without any explicit links in between.
+It is analogous to a
https://en.wikipedia.org/wiki/Dependency_injection[dependency injection]
framework, but curated for Log4j-specific needs.
+
+[NOTE]
+====
+Log4j plugin system is implemented by Log4j Core, the logging implementation.
+It is deliberately not a part of the Log4j API to keep the logging API
footprint small.
+====
+
+[TIP]
+====
+Did you know about *xref:plugin-reference.adoc[], the documentation extracted
from the source code* of all predefined Log4j plugins?
+Like Javadoc, but specialized for plugins!
+====
+
+In this section we will give an overview of the Log4j plugin system by
answering certain questions:
+
+. <<#declare-plugin,How can you declare a plugin?>>
+. <<#core,How can you declare a plugin that needs to be represented in a Log4j
configuration file?>>
+. <<#plugin-registry,How can you register your plugin to Log4j?>>
+. <<#plugin-discovery,How does Log4j discover plugins?>>
+. <<#plugin-load,How can you load other plugins in a plugin?>>
+
+[#declare-plugin]
+== Declaring plugins
+
+A class can be declared as a plugin by adding a
link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/Plugin.html[`@Plugin`]
annotation, which is essentially composed of following attributes:
+
+`name`::
+Name of the plugin.
+It is recommended to be distinct among plugins sharing the same `category`.
+`name` matching is case-insensitive.
+
+`category` (optional)::
+A name used for grouping a set of plugins.
+`category` matching is case-sensitive.
+
+`elementType` (optional)::
+Name of the corresponding category of the xref:manual/configuration.adoc[Log4j
configuration] file element this plugin belongs under.
+You can omit this attribute if your plugin is not meant to be represented in a
configuration file.
Review Comment:
Fixed in 242a7ed45a08a52ab79941cc9f83fafc171e7a33.
--
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]
