This is an automated email from the ASF dual-hosted git repository.
pkarwasz pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/logging-log4j-tools.git
The following commit(s) were added to refs/heads/main by this push:
new c1d23ab Adds a `log4j-docgen` module
c1d23ab is described below
commit c1d23abd72dc5e9ae9b949aae5803c9bc70f679b
Author: Piotr P. Karwasz <[email protected]>
AuthorDate: Wed Dec 20 19:51:22 2023 +0100
Adds a `log4j-docgen` module
The module contains a commons XML model to document a JARs containing
Log4j plugins.
Part of apache/logging-log4j2#1955.
---
log4j-docgen/pom.xml | 63 ++++
log4j-docgen/src/main/mdo/plugins-model.xml | 369 +++++++++++++++++++++
.../resources/META-INF/log4j/plugins-sample.xml | 293 ++++++++++++++++
log4j-tools-parent/pom.xml | 76 ++++-
pom.xml | 7 +
spotbugs-exclude.xml | 29 ++
src/changelog/.0.x.x/add_log4j_docgen.xml | 9 +
7 files changed, 836 insertions(+), 10 deletions(-)
diff --git a/log4j-docgen/pom.xml b/log4j-docgen/pom.xml
new file mode 100644
index 0000000..d8db344
--- /dev/null
+++ b/log4j-docgen/pom.xml
@@ -0,0 +1,63 @@
+<?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.logging.log4j</groupId>
+ <artifactId>log4j-tools-parent</artifactId>
+ <version>${revision}</version>
+ <relativePath>../log4j-tools-parent</relativePath>
+ </parent>
+
+ <artifactId>log4j-docgen</artifactId>
+
+ <properties>
+ <bnd.baseline.fail.on.missing>false</bnd.baseline.fail.on.missing>
+ </properties>
+
+ <build>
+ <plugins>
+
+ <plugin>
+ <groupId>org.codehaus.modello</groupId>
+ <artifactId>modello-maven-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>generate-model</id>
+ <goals>
+ <goal>java</goal>
+ <goal>stax-reader</goal>
+ <goal>stax-writer</goal>
+ <goal>xdoc</goal>
+ <goal>xsd</goal>
+ </goals>
+ <configuration>
+ <domAsXpp3>false</domAsXpp3>
+ <models>
+ <model>src/main/mdo/plugins-model.xml</model>
+ </models>
+ <version>0.1.0</version>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+
+ </plugins>
+ </build>
+
+</project>
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 0000000..d598ac6
--- /dev/null
+++ b/log4j-docgen/src/main/mdo/plugins-model.xml
@@ -0,0 +1,369 @@
+<?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.
+ -->
+<model xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xmlns="http://codehaus-plexus.github.io/MODELLO/2.0.0";
+ xsi:schemaLocation="http://codehaus-plexus.github.io/MODELLO/2.0.0
https://codehaus-plexus.github.io/modello/xsd/modello-2.0.0.xsd";
+ xml.namespace="https://logging.apache.org/log4j/plugins";>
+ <id>plugins</id>
+ <name>PluginSet</name>
+ <description>Documents a set of Log4j plugins.</description>
+ <versionDefinition>
+ <type>field</type>
+ <value>schemaVersion</value>
+ </versionDefinition>
+ <defaults>
+ <default>
+ <key>package</key>
+ <value>org.apache.logging.log4j.docgen</value>
+ </default>
+ </defaults>
+
+ <classes>
+ <class rootElement="true">
+ <name>PluginSet</name>
+ <description>Documents a set of Log4j plugins.</description>
+ <fields>
+ <field xml.attribute="true" xml.tagName="version">
+ <name>schemaVersion</name>
+ <type>String</type>
+ <required>true</required>
+ <description>The version of the schema used by the XML
document.</description>
+ </field>
+ <field>
+ <name>groupId</name>
+ <type>String</type>
+ <description>The group id of the set.</description>
+ </field>
+ <field>
+ <name>artifactId</name>
+ <type>String</type>
+ <description>The artifact id of the set.</description>
+ </field>
+ <field>
+ <name>version</name>
+ <type>String</type>
+ <description>The version of the set.</description>
+ </field>
+ <field>
+ <name>description</name>
+ <association>
+ <type>Description</type>
+ </association>
+ <description>Description of the set.</description>
+ </field>
+ <field>
+ <name>scalars</name>
+ <association>
+ <type>ScalarType</type>
+ <multiplicity>*</multiplicity>
+ </association>
+ <description>A list of all scalar types used in
properties.</description>
+ </field>
+ <field>
+ <name>plugins</name>
+ <association>
+ <type>PluginType</type>
+ <multiplicity>*</multiplicity>
+ </association>
+ <description>A list of all plugins in the
set.</description>
+ </field>
+ <field>
+ <name>abstractTypes</name>
+ <association>
+ <type>AbstractType</type>
+ <multiplicity>*</multiplicity>
+ </association>
+ <description>A description of all the interfaces and
extensible classes used in plugin elements.</description>
+ </field>
+ </fields>
+ </class>
+
+ <class>
+ <name>Documented</name>
+ <description>Any documented element.</description>
+ <fields>
+ <field>
+ <name>description</name>
+ <association>
+ <type>Description</type>
+ </association>
+ <required>true</required>
+ <description>Description of the plugin.</description>
+ </field>
+ </fields>
+ </class>
+
+ <class>
+ <name>Type</name>
+ <description>Any Java type used in a Log4j
configuration.</description>
+ <superClass>Documented</superClass>
+ <fields>
+ <field xml.attribute="true">
+ <name>className</name>
+ <type>String</type>
+ <required>true</required>
+ <description>Fully qualified name of the class
implementing the plugin.</description>
+ </field>
+ </fields>
+ </class>
+
+ <class>
+ <name>AbstractType</name>
+ <description>A documented interface or abstract class used in
plugins.</description>
+ <superClass>Type</superClass>
+ <fields>
+ <field xml.transient="true">
+ <name>implementations</name>
+ <association>
+ <type>String</type>
+ <multiplicity>*</multiplicity>
+ </association>
+ <description>Contains all the plugins that implement a
given type.
+<p>
+This element is filled in automatically.
+</p></description>
+ </field>
+ </fields>
+ </class>
+
+ <class xml.tagName="plugin">
+ <name>PluginType</name>
+ <description>Describes the properties available to
plugins.</description>
+ <superClass>AbstractType</superClass>
+ <fields>
+ <field xml.attribute="true">
+ <name>name</name>
+ <type>String</type>
+ <required>true</required>
+ <description>The unique name of this plugin.</description>
+ </field>
+ <field xml.attribute="true">
+ <name>namespace</name>
+ <type>String</type>
+ <defaultValue>Core</defaultValue>
+ <description>The namespace of the plugin.</description>
+ </field>
+ <field xml.attribute="true">
+ <name>deferChildren</name>
+ <type>boolean</type>
+ <defaultValue>false</defaultValue>
+ <description>If `true`, the evaluation of the children of
this element is deferred.</description>
+ </field>
+ <field>
+ <name>aliases</name>
+ <required>true</required>
+ <association xml.tagName="alias">
+ <type>String</type>
+ <multiplicity>*</multiplicity>
+ </association>
+ <description>
+ The different aliases keys (e.g. XML tag names) under
which the plugin can be used.
+ </description>
+ </field>
+ <!-- These are necessary to find all possible nested
components -->
+ <field>
+ <name>supertypes</name>
+ <association>
+ <type>String</type>
+ <multiplicity>*</multiplicity>
+ </association>
+ <description>
+ List of all the supertypes of a plugin.
+ </description>
+ </field>
+ <field>
+ <name>attributes</name>
+ <required>true</required>
+ <association>
+ <type>PluginAttribute</type>
+ <multiplicity>*</multiplicity>
+ </association>
+ <description>List of **all** the configuration attributes
supported</description>
+ </field>
+ <field>
+ <name>elements</name>
+ <required>true</required>
+ <association>
+ <type>PluginElement</type>
+ <multiplicity>*</multiplicity>
+ </association>
+ <description>List of **all** possible nested
components.</description>
+ </field>
+ </fields>
+ </class>
+
+ <class xml.tagName="attribute">
+ <name>PluginAttribute</name>
+ <description>A scalar configuration value for the
plugin.</description>
+ <fields>
+ <field xml.attribute="true">
+ <name>name</name>
+ <type>String</type>
+ <required>true</required>
+ <description>The name of the property.</description>
+ </field>
+ <field xml.attribute="true">
+ <name>type</name>
+ <type>String</type>
+ <defaultValue>java.lang.String</defaultValue>
+ <description>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.</description>
+ </field>
+ <field xml.attribute="true">
+ <name>required</name>
+ <type>boolean</type>
+ <defaultValue>false</defaultValue>
+ <description>If set to `true` the attribute is
required.</description>
+ </field>
+ <field xml.attribute="true">
+ <name>defaultValue</name>
+ <type>String</type>
+ <description>The default value of this attribute as
string.</description>
+ </field>
+ <field xml.attribute="true">
+ <name>defaultProperty</name>
+ <type>String</type>
+ <description>The Log4j property that contains the default
value of this attribute.</description>
+ </field>
+ <field>
+ <name>description</name>
+ <association>
+ <type>Description</type>
+ </association>
+ <description>A description of the property.</description>
+ </field>
+ </fields>
+ </class>
+
+ <class xml.tagName="scalar">
+ <name>ScalarType</name>
+ <description>Describes a Java type that can be converted to a
string.</description>
+ <superClass>Type</superClass>
+ <fields>
+ <field>
+ <name>values</name>
+ <required>true</required>
+ <association>
+ <type>ScalarValue</type>
+ <multiplicity>*</multiplicity>
+ </association>
+ <description>The possible string values of this
type.</description>
+ </field>
+ </fields>
+ </class>
+
+ <class xml.tagName="description">
+ <name>Description</name>
+ <description>General documentation tag.</description>
+ <fields>
+ <field xml.attribute="true">
+ <name>format</name>
+ <type>String</type>
+ <defaultValue>asciidoc</defaultValue>
+ <description>Format used by the documentation text.
Currently it **must** be `asciidoc`.
+ </description>
+ </field>
+ <field xml.content="true" xml.trim="false">
+ <name>text</name>
+ <type>String</type>
+ <required>true</required>
+ <description>Description of the element.</description>
+ </field>
+ </fields>
+ </class>
+
+ <class xml.tagName="value">
+ <name>ScalarValue</name>
+ <description>One of the possible values of a scalar Java
type.</description>
+ <fields>
+ <field xml.attribute="true">
+ <name>name</name>
+ <type>String</type>
+ <required>true</required>
+ <description>The name of the value.</description>
+ </field>
+ <field>
+ <name>description</name>
+ <association>
+ <type>Description</type>
+ </association>
+ <description>The description of the value.</description>
+ </field>
+ </fields>
+ </class>
+
+ <class xml.tagName="element">
+ <name>PluginElement</name>
+ <description>Describes a nested configuration
component.</description>
+ <fields>
+ <field xml.attribute="true">
+ <name>multiplicity</name>
+ <type>String</type>
+ <defaultValue>1</defaultValue>
+ <description>Either `*`, if the field accepts a collection
of elements, or `1`.</description>
+ </field>
+ <field xml.attribute="true">
+ <name>required</name>
+ <type>boolean</type>
+ <defaultValue>false</defaultValue>
+ <description>If set to `true` the field must be not null
or a not empty collection.</description>
+ </field>
+ <field xml.attribute="true">
+ <name>type</name>
+ <type>String</type>
+ <required>true</required>
+ <description>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>
+ </field>
+ <field>
+ <name>description</name>
+ <association>
+ <type>Description</type>
+ </association>
+ <description>An HTML description of this
element.</description>
+ </field>
+ </fields>
+ </class>
+ <!-- Models for various generators -->
+ <class>
+ <name>DocumentationRequest</name>
+ <fields>
+ <field xml.transient="true">
+ <name>pluginSets</name>
+ <association>
+ <type>PluginSet</type>
+ <multiplicity>*</multiplicity>
+ </association>
+ <required>true</required>
+ <description>The set of plugins to document.</description>
+ </field>
+ <field xml.transient="true">
+ <name>outputDirectory</name>
+ <association>
+ <type>java.nio.file.Path</type>
+ </association>
+ <required>true</required>
+ <description>The directory to use for output.</description>
+ </field>
+ </fields>
+ </class>
+ <!-- External classes -->
+ <class java.enabled="false">
+ <name>java.nio.file.Path</name>
+ </class>
+ </classes>
+</model>
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 0000000..81b300a
--- /dev/null
+++ b/log4j-docgen/src/test/resources/META-INF/log4j/plugins-sample.xml
@@ -0,0 +1,293 @@
+<?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.
+ -->
+<pluginSet xmlns="https://logging.apache.org/log4j/plugins"; version="0.1.0">
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-core</artifactId>
+ <version>2.22.0</version>
+ <description>Reference implementation of the Log4j API.</description>
+
+ <scalars>
+ <scalar
className="org.apache.logging.log4j.core.appender.ConsoleAppender.Target">
+ <description>Specifies the target of a console
appender.</description>
+ <values>
+ <value name="SYSTEM_OUT">
+ <description>Logs to the standard output.</description>
+ </value>
+ <value name="SYSTEM_ERR">
+ <description>Logs to the standard error.</description>
+ </value>
+ </values>
+ </scalar>
+ <scalar className="org.apache.logging.log4j.core.Filter.Result">
+ <description>The result that can returned from a filter method
call.</description>
+ <values>
+ <value name="ACCEPT">
+ <description>The event will be processed without further
filtering based on the log Level.</description>
+ </value>
+ <value name="NEUTRAL">
+ <description>No decision could be made, further filtering
should occur.</description>
+ </value>
+ <value name="DENY">
+ <description>The event should not be
processed.</description>
+ </value>
+ </values>
+ </scalar>
+ </scalars>
+
+ <plugins>
+ <!-- Direct children of Configuration -->
+ <plugin name="Appenders"
className="org.apache.logging.log4j.core.config.AppendersPlugin">
+ <description>A wrapper for a list of appenders.</description>
+ <elements>
+ <element type="org.apache.logging.log4j.core.Appender"
multiplicity="*">
+ <description>A list of appender.</description>
+ </element>
+ </elements>
+ </plugin>
+
+ <plugin name="CustomLevels"
className="org.apache.logging.log4j.core.config.CustomLevels">
+ <description>A wrapper for a list of custom level
configurations.</description>
+ <elements>
+ <element
type="org.apache.logging.log4j.core.config.CustomLevelConfig" multiplicity="*">
+ <description>A list of custom level
configurations.</description>
+ </element>
+ </elements>
+ </plugin>
+
+ <plugin name="Loggers"
className="org.apache.logging.log4j.core.config.LoggersPlugin">
+ <description>A wrapper for a list of logger
configurations.</description>
+ <elements>
+ <element
type="org.apache.logging.log4j.core.config.LoggerConfig" multiplicity="*">
+ <description>A list of logger configurations.</description>
+ </element>
+ </elements>
+ </plugin>
+
+ <plugin name="Properties"
className="org.apache.logging.log4j.core.config.PropertiesPlugin">
+ <description>A wrapper for a list of properties.</description>
+ <elements>
+ <element type="org.apache.logging.log4j.core.config.Property"
multiplicity="*">
+ <description>A list of properties.</description>
+ </element>
+ </elements>
+ </plugin>
+
+ <!-- Second nesting level elements -->
+ <plugin name="Console"
className="org.apache.logging.log4j.core.appender.ConsoleAppender">
+ <supertypes>
+ <supertype>org.apache.logging.log4j.core.Appender</supertype>
+ </supertypes>
+ <description>Write log events to the console.</description>
+ <attributes>
+ <attribute name="name" required="true">
+ <description>The name of the appender used in appender
references.
+Must be unique.</description>
+ </attribute>
+ <attribute name="ignoreExceptions" type="boolean"
defaultValue="true">
+ <description>If set to `false` logging exceptions will be
forwarded to the caller.</description>
+ </attribute>
+ <attribute name="bufferedIo" type="boolean"
defaultValue="true">
+ <description>If set to `true` (default) the appender will
buffer messages before sending them.
+This attribute is ignored if `immediateFlush` is set to `true`.</description>
+ </attribute>
+ <attribute name="bufferSize" type="int"
defaultProperty="log4j2.encoderByteBufferSize">
+ <description>Size in bytes of the appender's
buffer.</description>
+ </attribute>
+ <attribute name="immediateFlush" type="boolean"
defaultValue="true">
+ <description>If set to `true`, the appender flushes the
output stream at each message and
+buffering is disabled regardless of the value of `bufferedIo`.</description>
+ </attribute>
+ <attribute name="target"
type="org.apache.logging.log4j.core.appender.ConsoleAppender.Target"
+ defaultValue="SYSTEM_OUT">
+ <description>Specifies the target of the
appender.</description>
+ </attribute>
+ </attributes>
+ <elements>
+ <element type="org.apache.logging.log4j.core.Filter">
+ <description>A filter to apply to events before sending
them to destination.</description>
+ </element>
+ <element type="org.apache.logging.log4j.core.Layout"
required="true">
+ <description>The layout to be used with the
appender.</description>
+ </element>
+ </elements>
+ </plugin>
+
+ <plugin name="CustomLevel"
className="org.apache.logging.log4j.core.config.CustomLevelConfig">
+ <description>Configures a custom level.</description>
+ <attributes>
+ <attribute name="name" required="true">
+ <description>The name of the level.</description>
+ </attribute>
+ <attribute name="intLevel" type="int" required="true">
+ <description>An integer determines the strength of the
custom level relative to the built-in levels.</description>
+ </attribute>
+ </attributes>
+ </plugin>
+
+ <plugin name="Logger"
className="org.apache.logging.log4j.core.config.LoggerConfig">
+ <description>Configures a particular logger</description>
+ <attributes>
+ <attribute name="name" required="true">
+ <description>The name of the logger.</description>
+ </attribute>
+ <attribute name="level" type="org.apache.logging.log4j.Level">
+ <description>The level of the logger.</description>
+ </attribute>
+ <attribute name="includeLocation" type="boolean">
+ <description>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`.</description>
+ </attribute>
+ </attributes>
+ <elements>
+ <element
type="org.apache.logging.log4j.core.config.AppenderRef" multiplicity="*">
+ <description>A list of appenders to use with this
logger.</description>
+ </element>
+ <element type="org.apache.logging.log4j.core.Filter">
+ <description>A filter to filter events, before calling the
appenders.</description>
+ </element>
+ </elements>
+ </plugin>
+
+ <plugin name="Root"
className="org.apache.logging.log4j.core.config.LoggerConfig.RootLogger">
+ <description>Configures the root logger</description>
+ <supertypes>
+
<supertype>org.apache.logging.log4j.core.config.LoggerConfig</supertype>
+ </supertypes>
+ <attributes>
+ <attribute name="level" type="org.apache.logging.log4j.Level"
defaultValue="ERROR">
+ <description>The level of the logger.</description>
+ </attribute>
+ <attribute name="includeLocation" type="boolean">
+ <description>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`.</description>
+ </attribute>
+ </attributes>
+ <elements>
+ <element
type="org.apache.logging.log4j.core.config.AppenderRef" multiplicity="*">
+ <description>A list of appenders to use with this
logger.</description>
+ </element>
+ <element type="org.apache.logging.log4j.core.Filter">
+ <description>A filter to filter events, before calling the
appenders.</description>
+ </element>
+ </elements>
+ </plugin>
+
+ <plugin name="Property"
className="org.apache.logging.log4j.core.config.Property">
+ <description>Represents a key/value pair in the
configuration.</description>
+ <attributes>
+ <attribute name="name" required="true">
+ <description>Name of the property.</description>
+ </attribute>
+ <attribute name="value">
+ <description>Value of the property.</description>
+ </attribute>
+ </attributes>
+ </plugin>
+
+ <!-- Additional plugins -->
+ <plugin name="AppenderRef"
className="org.apache.logging.log4j.core.config.AppenderRef">
+ <description>Reference to an appender defined in the `Appenders`
section.</description>
+ <aliases>
+ <alias>appender-ref</alias>
+ </aliases>
+ <attributes>
+ <attribute name="ref" required="true">
+ <description>The name of an appender.</description>
+ </attribute>
+ <attribute name="level" type="org.apache.logging.log4j.Level">
+ <description>The level to filter against.</description>
+ </attribute>
+ </attributes>
+ <elements>
+ <element type="org.apache.logging.log4j.core.Filter">
+ <description>The filter to use.</description>
+ </element>
+ </elements>
+ </plugin>
+
+ <plugin name="BurstFilter"
className="org.apache.logging.log4j.core.filter.BurstFilter">
+ <description>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.</description>
+ <supertypes>
+ <supertype>org.apache.logging.log4j.core.Filter</supertype>
+ </supertypes>
+ <attributes>
+ <attribute name="onMatch"
type="org.apache.logging.log4j.core.Filter.Result" defaultValue="NEUTRAL">
+ <description>Action to perform if the filter
matches.</description>
+ </attribute>
+ <attribute name="onMismatch"
type="org.apache.logging.log4j.core.Filter.Result" defaultValue="DENY">
+ <description>Action to perform if the filter does not
match.</description>
+ </attribute>
+ <attribute name="level" type="org.apache.logging.log4j.Level"
defaultValue="WARN">
+ <description>Log events less specific than this level are
filtered, while events with level equal or more specific always
match.</description>
+ </attribute>
+ <attribute name="rate" type="float" defaultValue="10">
+ <description>Sets the average number of events per second
to allow.</description>
+ </attribute>
+ <attribute name="maxBurst" type="long">
+ <description>Sets the maximum number of events that can
occur before events are filtered for exceeding the average rate.</description>
+ </attribute>
+ </attributes>
+ </plugin>
+
+ <plugin name="PatternLayout"
className="org.apache.logging.log4j.core.layout.PatternLayout">
+ <description>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_.</description>
+ <supertypes>
+ <supertype>org.apache.logging.log4j.core.Layout</supertype>
+ </supertypes>
+ <attributes>
+ <attribute name="pattern" defaultValue="%m%n">
+ <description>The pattern to use to format log
events.</description>
+ </attribute>
+ </attributes>
+ </plugin>
+ </plugins>
+
+ <abstractTypes>
+ <abstractType className="org.apache.logging.log4j.core.Appender">
+ <description>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.</description>
+ </abstractType>
+ <abstractType className="org.apache.logging.log4j.core.Filter">
+ <description>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.</description>
+ </abstractType>
+ <abstractType className="org.apache.logging.log4j.core.Layout">
+ <description>A layout is responsible for formatting a `LogEvent`
as a string.</description>
+ </abstractType>
+ </abstractTypes>
+</pluginSet>
diff --git a/log4j-tools-parent/pom.xml b/log4j-tools-parent/pom.xml
index d47e485..4353706 100644
--- a/log4j-tools-parent/pom.xml
+++ b/log4j-tools-parent/pom.xml
@@ -31,19 +31,34 @@
<properties>
- <!-- dependency versions -->
+ <!-- Dependency versions -->
<assertj.version>3.24.2</assertj.version>
<commons-io.version>2.15.1</commons-io.version>
<freemarker.version>2.3.32</freemarker.version>
+ <jakarta.inject.version>1.0.5</jakarta.inject.version>
<junit.version>5.10.1</junit.version>
+ <modello.version>2.1.2</modello.version>
+ <xmlunit.version>2.9.1</xmlunit.version>
+
+ <!-- Maven plugin versions -->
<maven-plugin.version>3.10.2</maven-plugin.version>
<maven-plugin-api.version>3.6.3</maven-plugin-api.version>
+
<modello-maven-plugin.version>${modello.version}</modello-maven-plugin.version>
+ <sisu-maven-plugin.version>0.9.0.M2</sisu-maven-plugin.version>
</properties>
<dependencyManagement>
<dependencies>
+ <dependency>
+ <groupId>org.junit</groupId>
+ <artifactId>junit-bom</artifactId>
+ <version>${junit.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+
<dependency>
<groupId>org.assertj</groupId>
<artifactId>assertj-core</artifactId>
@@ -63,15 +78,9 @@
</dependency>
<dependency>
- <groupId>org.junit.jupiter</groupId>
- <artifactId>junit-jupiter-engine</artifactId>
- <version>${junit.version}</version>
- </dependency>
-
- <dependency>
- <groupId>org.junit.jupiter</groupId>
- <artifactId>junit-jupiter-params</artifactId>
- <version>${junit.version}</version>
+ <groupId>jakarta.inject</groupId>
+ <artifactId>jakarta.inject-api</artifactId>
+ <version>${jakarta.inject.version}</version>
</dependency>
<dependency>
@@ -88,7 +97,54 @@
<scope>provided</scope>
</dependency>
+ <dependency>
+ <groupId>org.xmlunit</groupId>
+ <artifactId>xmlunit-assertj3</artifactId>
+ <version>${xmlunit.version}</version>
+ </dependency>
+
</dependencies>
</dependencyManagement>
+ <dependencies>
+
+ <dependency>
+ <groupId>org.osgi</groupId>
+ <artifactId>org.osgi.annotation.bundle</artifactId>
+ <scope>provided</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>org.osgi</groupId>
+ <artifactId>org.osgi.annotation.versioning</artifactId>
+ <scope>provided</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>com.github.spotbugs</groupId>
+ <artifactId>spotbugs-annotations</artifactId>
+ <scope>provided</scope>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <pluginManagement>
+ <plugins>
+
+ <plugin>
+ <groupId>org.codehaus.modello</groupId>
+ <artifactId>modello-maven-plugin</artifactId>
+ <version>${modello-maven-plugin.version}</version>
+ </plugin>
+
+ <plugin>
+ <groupId>org.eclipse.sisu</groupId>
+ <artifactId>sisu-maven-plugin</artifactId>
+ <version>${sisu-maven-plugin.version}</version>
+ </plugin>
+
+ </plugins>
+ </pluginManagement>
+ </build>
+
</project>
diff --git a/pom.xml b/pom.xml
index 0bd5370..eeb150a 100644
--- a/pom.xml
+++ b/pom.xml
@@ -86,6 +86,7 @@
<!-- Modules here must have a corresponding entry in `dependencyManagement
> dependencies` block below! -->
<module>log4j-changelog</module>
<module>log4j-changelog-maven-plugin</module>
+ <module>log4j-docgen</module>
</modules>
@@ -147,6 +148,12 @@
<version>${project.version}</version>
</dependency>
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-docgen</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+
</dependencies>
</dependencyManagement>
diff --git a/spotbugs-exclude.xml b/spotbugs-exclude.xml
new file mode 100644
index 0000000..4e63cb7
--- /dev/null
+++ b/spotbugs-exclude.xml
@@ -0,0 +1,29 @@
+<?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.
+ -->
+<FindBugsFilter
+ xmlns="https://github.com/spotbugs/filter/3.0.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="https://github.com/spotbugs/filter/3.0.0
https://raw.githubusercontent.com/spotbugs/spotbugs/3.1.0/spotbugs/etc/findbugsfilter.xsd";>
+ <!-- We exclude warnings from sources generated by Modello.
+ TODO: solve those warnings in Modello. -->
+ <Match>
+ <Not>
+ <Source name="~target/generated-sources/.*"/>
+ </Not>
+ </Match>
+</FindBugsFilter>
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 0000000..3950a76
--- /dev/null
+++ b/src/changelog/.0.x.x/add_log4j_docgen.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<entry xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xmlns="http://logging.apache.org/log4j/changelog";
+ xsi:schemaLocation="http://logging.apache.org/log4j/changelog
https://logging.apache.org/log4j/changelog-0.1.2.xsd";
+ type="added">
+ <description format="asciidoc">
+ Add a `log4j-docgen` module with a common XML model to document sets of
Log4j plugins.
+ </description>
+</entry>
