diff --git a/log4j-docgen/pom.xml b/log4j-docgen/pom.xml
new file mode 100644
index 00000000..d8db3447
--- /dev/null
+++ b/log4j-docgen/pom.xml
@@ -0,0 +1,63 @@
+
+
+
+ 4.0.0
+
+ org.apache.logging.log4j
+ log4j-tools-parent
+ ${revision}
+ ../log4j-tools-parent
+
+
+ log4j-docgen
+
+
+ false
+
+
+
+
+
+
+ org.codehaus.modello
+ modello-maven-plugin
+
+
+ generate-model
+
+ java
+ stax-reader
+ stax-writer
+ xdoc
+ xsd
+
+
+ false
+
+ src/main/mdo/plugins-model.xml
+
+ 0.1.0
+
+
+
+
+
+
+
+
+
diff --git a/log4j-docgen/src/main/mdo/plugins-model.xml b/log4j-docgen/src/main/mdo/plugins-model.xml
new file mode 100644
index 00000000..d598ac67
--- /dev/null
+++ b/log4j-docgen/src/main/mdo/plugins-model.xml
@@ -0,0 +1,369 @@
+
+
+
+ plugins
+ PluginSet
+ Documents a set of Log4j plugins.
+
+ field
+ schemaVersion
+
+
+
+ package
+ org.apache.logging.log4j.docgen
+
+
+
+
+
+ PluginSet
+ Documents a set of Log4j plugins.
+
+
+ schemaVersion
+ String
+ true
+ The version of the schema used by the XML document.
+
+
+ groupId
+ String
+ The group id of the set.
+
+
+ artifactId
+ String
+ The artifact id of the set.
+
+
+ version
+ String
+ The version of the set.
+
+
+ description
+
+ Description
+
+ Description of the set.
+
+
+ scalars
+
+ ScalarType
+ *
+
+ A list of all scalar types used in properties.
+
+
+ plugins
+
+ PluginType
+ *
+
+ A list of all plugins in the set.
+
+
+ abstractTypes
+
+ AbstractType
+ *
+
+ A description of all the interfaces and extensible classes used in plugin elements.
+
+
+
+
+
+ Documented
+ Any documented element.
+
+
+ description
+
+ Description
+
+ true
+ Description of the plugin.
+
+
+
+
+
+ Type
+ Any Java type used in a Log4j configuration.
+ Documented
+
+
+ className
+ String
+ true
+ Fully qualified name of the class implementing the plugin.
+
+
+
+
+
+ AbstractType
+ A documented interface or abstract class used in plugins.
+ Type
+
+
+ implementations
+
+ String
+ *
+
+ Contains all the plugins that implement a given type.
+<p>
+This element is filled in automatically.
+</p>
+
+
+
+
+
+ PluginType
+ Describes the properties available to plugins.
+ AbstractType
+
+
+ name
+ String
+ true
+ The unique name of this plugin.
+
+
+ namespace
+ String
+ Core
+ The namespace of the plugin.
+
+
+ deferChildren
+ boolean
+ false
+ If `true`, the evaluation of the children of this element is deferred.
+
+
+ aliases
+ true
+
+ String
+ *
+
+
+ The different aliases keys (e.g. XML tag names) under which the plugin can be used.
+
+
+
+
+ supertypes
+
+ String
+ *
+
+
+ List of all the supertypes of a plugin.
+
+
+
+ attributes
+ true
+
+ PluginAttribute
+ *
+
+ List of **all** the configuration attributes supported
+
+
+ elements
+ true
+
+ PluginElement
+ *
+
+ List of **all** possible nested components.
+
+
+
+
+
+ PluginAttribute
+ A scalar configuration value for the plugin.
+
+
+ name
+ String
+ true
+ The name of the property.
+
+
+ type
+ String
+ java.lang.String
+ The Java name of this attribute's type, e.g. `boolean`, `java.lang.String`, fully qualified name of an enum.
+The type must be an enum or must have a type converter.
+
+
+ required
+ boolean
+ false
+ If set to `true` the attribute is required.
+
+
+ defaultValue
+ String
+ The default value of this attribute as string.
+
+
+ defaultProperty
+ String
+ The Log4j property that contains the default value of this attribute.
+
+
+ description
+
+ Description
+
+ A description of the property.
+
+
+
+
+
+ ScalarType
+ Describes a Java type that can be converted to a string.
+ Type
+
+
+ values
+ true
+
+ ScalarValue
+ *
+
+ The possible string values of this type.
+
+
+
+
+
+ Description
+ General documentation tag.
+
+
+ format
+ String
+ asciidoc
+ Format used by the documentation text. Currently it **must** be `asciidoc`.
+
+
+
+ text
+ String
+ true
+ Description of the element.
+
+
+
+
+
+ ScalarValue
+ One of the possible values of a scalar Java type.
+
+
+ name
+ String
+ true
+ The name of the value.
+
+
+ description
+
+ Description
+
+ The description of the value.
+
+
+
+
+
+ PluginElement
+ Describes a nested configuration component.
+
+
+ multiplicity
+ String
+ 1
+ Either `*`, if the field accepts a collection of elements, or `1`.
+
+
+ required
+ boolean
+ false
+ If set to `true` the field must be not null or a not empty collection.
+
+
+ type
+ String
+ true
+ The fully qualified name of the Java type (class or interface) of this component.
+If the type is an array or collection, this returns the type of the element.
+
+
+ description
+
+ Description
+
+ An HTML description of this element.
+
+
+
+
+
+ DocumentationRequest
+
+
+ pluginSets
+
+ PluginSet
+ *
+
+ true
+ The set of plugins to document.
+
+
+ outputDirectory
+
+ java.nio.file.Path
+
+ true
+ The directory to use for output.
+
+
+
+
+
+ java.nio.file.Path
+
+
+
diff --git a/log4j-docgen/src/test/resources/META-INF/log4j/plugins-sample.xml b/log4j-docgen/src/test/resources/META-INF/log4j/plugins-sample.xml
new file mode 100644
index 00000000..81b300a4
--- /dev/null
+++ b/log4j-docgen/src/test/resources/META-INF/log4j/plugins-sample.xml
@@ -0,0 +1,293 @@
+
+
+
+ org.apache.logging.log4j
+ log4j-core
+ 2.22.0
+ Reference implementation of the Log4j API.
+
+
+
+ Specifies the target of a console appender.
+
+
+ Logs to the standard output.
+
+
+ Logs to the standard error.
+
+
+
+
+ The result that can returned from a filter method call.
+
+
+ The event will be processed without further filtering based on the log Level.
+
+
+ No decision could be made, further filtering should occur.
+
+
+ The event should not be processed.
+
+
+
+
+
+
+
+
+ A wrapper for a list of appenders.
+
+
+ A list of appender.
+
+
+
+
+
+ A wrapper for a list of custom level configurations.
+
+
+ A list of custom level configurations.
+
+
+
+
+
+ A wrapper for a list of logger configurations.
+
+
+ A list of logger configurations.
+
+
+
+
+
+ A wrapper for a list of properties.
+
+
+ A list of properties.
+
+
+
+
+
+
+
+ org.apache.logging.log4j.core.Appender
+
+ Write log events to the console.
+
+
+ The name of the appender used in appender references.
+Must be unique.
+
+
+ If set to `false` logging exceptions will be forwarded to the caller.
+
+
+ If set to `true` (default) the appender will buffer messages before sending them.
+This attribute is ignored if `immediateFlush` is set to `true`.
+
+
+ Size in bytes of the appender's buffer.
+
+
+ If set to `true`, the appender flushes the output stream at each message and
+buffering is disabled regardless of the value of `bufferedIo`.
+
+
+ Specifies the target of the appender.
+
+
+
+
+ A filter to apply to events before sending them to destination.
+
+
+ The layout to be used with the appender.
+
+
+
+
+
+ Configures a custom level.
+
+
+ The name of the level.
+
+
+ An integer determines the strength of the custom level relative to the built-in levels.
+
+
+
+
+
+ Configures a particular logger
+
+
+ The name of the logger.
+
+
+ The level of the logger.
+
+
+ When set to `false` location information will **not** be computed.
+
+The default value depends on the logger context implementation: it is `false` for `AsyncLoggerContext` and `true` for `LoggerContext`.
+
+
+
+
+ A list of appenders to use with this logger.
+
+
+ A filter to filter events, before calling the appenders.
+
+
+
+
+
+ Configures the root logger
+
+ org.apache.logging.log4j.core.config.LoggerConfig
+
+
+
+ The level of the logger.
+
+
+ When set to `false` location information will **not** be computed.
+
+The default value depends on the logger context implementation: it is `false` for `AsyncLoggerContext` and `true` for `LoggerContext`.
+
+
+
+
+ A list of appenders to use with this logger.
+
+
+ A filter to filter events, before calling the appenders.
+
+
+
+
+
+ Represents a key/value pair in the configuration.
+
+
+ Name of the property.
+
+
+ Value of the property.
+
+
+
+
+
+
+ Reference to an appender defined in the `Appenders` section.
+
+ appender-ref
+
+
+
+ The name of an appender.
+
+
+ The level to filter against.
+
+
+
+
+ The filter to use.
+
+
+
+
+
+ The BurstFilter is a logging filter that regulates logging traffic.
+Use this filter when you want to control the mean rate and maximum burst of log statements that can be sent to an appender.
+
+ org.apache.logging.log4j.core.Filter
+
+
+
+ Action to perform if the filter matches.
+
+
+ Action to perform if the filter does not match.
+
+
+ Log events less specific than this level are filtered, while events with level equal or more specific always match.
+
+
+ Sets the average number of events per second to allow.
+
+
+ Sets the maximum number of events that can occur before events are filtered for exceeding the average rate.
+
+
+
+
+
+ A flexible layout configurable with pattern string.
+
+The goal of this class is to {@link org.apache.logging.log4j.core.Layout#toByteArray format} a {@link LogEvent} and return the results.
+The format of the result depends on the _conversion pattern_.
+
+The conversion pattern is closely related to the conversion pattern of the printf function in C.
+A conversion pattern is composed of literal text and format control expressions called _conversion specifiers_.
+
+ org.apache.logging.log4j.core.Layout
+
+
+
+ The pattern to use to format log events.
+
+
+
+
+
+
+
+ Appends log events.
+An Appender can contain a `Layout` if applicable as well as an `ErrorHandler`.
+Typical Appender implementations coordinate with an implementation of `AbstractManager` to handle external resources such as streams, connections, and other shared state.
+As Appenders are plugins, concrete implementations need to be annotated with `@Plugin` and need to provide a static factory method annotated with `@PluginFactory`.
+
+Most core plugins are written using a related Manager class that handle the actual task of serializing a `LogEvent` to some output location.
+For instance, many Appenders can take advantage of the `@OutputStreamManager` class.
+
+It is recommended that Appenders don't do any heavy lifting since there can be many instances of the class being used at any given time.
+When resources require locking (e.g., through `@FileLock`), it is important to isolate synchronized code to prevent concurrency issues.
+
+
+ Interface that must be implemented to allow custom event filtering.
+It is highly recommended that applications make use of the filters provided with this Log4j Core before creating their own.
+
+This interface supports "global" filters (i.e. - all events must pass through them first), attached to specific loggers and associated with Appenders.
+It is recommended that, where possible, `Filter` implementations create a generic filtering method that can be called from any of the filter methods.
+
+
+ A layout is responsible for formatting a `LogEvent` as a string.
+
+
+
diff --git a/log4j-tools-parent/pom.xml b/log4j-tools-parent/pom.xml
index d47e4851..43537068 100644
--- a/log4j-tools-parent/pom.xml
+++ b/log4j-tools-parent/pom.xml
@@ -31,19 +31,34 @@
-
+
3.24.22.15.12.3.32
+ 1.0.55.10.1
+ 2.1.2
+ 2.9.1
+
+
3.10.23.6.3
+ ${modello.version}
+ 0.9.0.M2
+
+ org.junit
+ junit-bom
+ ${junit.version}
+ pom
+ import
+
+
org.assertjassertj-core
@@ -63,15 +78,9 @@
- org.junit.jupiter
- junit-jupiter-engine
- ${junit.version}
-
-
-
- org.junit.jupiter
- junit-jupiter-params
- ${junit.version}
+ jakarta.inject
+ jakarta.inject-api
+ ${jakarta.inject.version}
@@ -88,7 +97,54 @@
provided
+
+ org.xmlunit
+ xmlunit-assertj3
+ ${xmlunit.version}
+
+
+
+
+
+ org.osgi
+ org.osgi.annotation.bundle
+ provided
+
+
+
+ org.osgi
+ org.osgi.annotation.versioning
+ provided
+
+
+
+ com.github.spotbugs
+ spotbugs-annotations
+ provided
+
+
+
+
+
+
+
+
+ org.codehaus.modello
+ modello-maven-plugin
+ ${modello-maven-plugin.version}
+
+
+
+ org.eclipse.sisu
+ sisu-maven-plugin
+ ${sisu-maven-plugin.version}
+
+
+
+
+
+
diff --git a/pom.xml b/pom.xml
index 0bd53708..eeb150ad 100644
--- a/pom.xml
+++ b/pom.xml
@@ -86,6 +86,7 @@
log4j-changeloglog4j-changelog-maven-plugin
+ log4j-docgen
@@ -147,6 +148,12 @@
${project.version}
+
+ org.apache.logging.log4j
+ log4j-docgen
+ ${project.version}
+
+
diff --git a/spotbugs-exclude.xml b/spotbugs-exclude.xml
new file mode 100644
index 00000000..4e63cb7a
--- /dev/null
+++ b/spotbugs-exclude.xml
@@ -0,0 +1,29 @@
+
+
+
+
+
+
+
+
+
+
diff --git a/src/changelog/.0.x.x/add_log4j_docgen.xml b/src/changelog/.0.x.x/add_log4j_docgen.xml
new file mode 100644
index 00000000..3950a760
--- /dev/null
+++ b/src/changelog/.0.x.x/add_log4j_docgen.xml
@@ -0,0 +1,9 @@
+
+
+
+ Add a `log4j-docgen` module with a common XML model to document sets of Log4j plugins.
+
+