You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by pk...@apache.org on 2023/11/28 19:03:50 UTC
(logging-log4j-tools) branch doc-reference created (now 50e73e6)
This is an automated email from the ASF dual-hosted git repository.
pkarwasz pushed a change to branch doc-reference
in repository https://gitbox.apache.org/repos/asf/logging-log4j-tools.git
at 50e73e6 Add example of documentation reference
This branch includes the following new commits:
new 50e73e6 Add example of documentation reference
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(logging-log4j-tools) 01/01: Add example of documentation reference
Posted by pk...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
pkarwasz pushed a commit to branch doc-reference
in repository https://gitbox.apache.org/repos/asf/logging-log4j-tools.git
commit 50e73e6d41d56b687cf12f34a2797630d79dfcbc
Author: Piotr P. Karwasz <pi...@karwasz.org>
AuthorDate: Tue Nov 28 19:43:49 2023 +0100
Add example of documentation reference
This commit contains a set of AsciiDoc documents to evaluate the
requirements for our documentation reference.
---
log4j-doc-reference/pom.xml | 58 +++++
.../org.apache.logging.log4j.core.Appender.adoc | 49 ++++
...ogging.log4j.core.appender.ConsoleAppender.adoc | 80 +++++++
....logging.log4j.core.config.AppendersPlugin.adoc | 43 ++++
...he.logging.log4j.core.config.Configuration.adoc | 93 ++++++++
log4j-doc-reference/src/site/Properties/index.adoc | 83 +++++++
.../src/site/TypeConverters/index.adoc | 56 +++++
.../src/test/resources/log4j-plugins.xml | 150 ++++++++++++
log4j-doc-reference/src/test/resources/log4j.xsd | 265 +++++++++++++++++++++
pom.xml | 1 +
10 files changed, 878 insertions(+)
diff --git a/log4j-doc-reference/pom.xml b/log4j-doc-reference/pom.xml
new file mode 100644
index 0000000..084ade1
--- /dev/null
+++ b/log4j-doc-reference/pom.xml
@@ -0,0 +1,58 @@
+<?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-doc-reference</artifactId>
+
+ <properties>
+ <bnd.baseline.fail.on.missing>false</bnd.baseline.fail.on.missing>
+
+ <!-- Pinned transitive dependencies -->
+ <sisu.plexus.version>0.9.0.M2</sisu.plexus.version>
+ </properties>
+
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.eclipse.sisu</groupId>
+ <artifactId>org.eclipse.sisu.plexus</artifactId>
+ <version>${sisu.plexus.version}</version>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-core</artifactId>
+ <version>2.22.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.codehaus.modello</groupId>
+ <artifactId>modello-plugin-xsd</artifactId>
+ <version>2.1.2</version>
+ </dependency>
+ </dependencies>
+</project>
diff --git a/log4j-doc-reference/src/site/Core/org.apache.logging.log4j.core.Appender.adoc b/log4j-doc-reference/src/site/Core/org.apache.logging.log4j.core.Appender.adoc
new file mode 100644
index 0000000..01ef932
--- /dev/null
+++ b/log4j-doc-reference/src/site/Core/org.apache.logging.log4j.core.Appender.adoc
@@ -0,0 +1,49 @@
+////
+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
+
+ https://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.
+////
+= Appender
+
+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.
+
+== Known implementations
+
+[cols="1,1,5m"]
+|===
+|Tag
+|Type
+|Description
+
+|`Console`
+|xref:org.apache.logging.log4j.core.appender.ConsoleAppender.adoc[ConsoleAppender]
+|An appender the writes to `System.out` or `System.err`.
+
+|`File`
+|FileAppender
+|An appender that writes to a file.
+|===
diff --git a/log4j-doc-reference/src/site/Core/org.apache.logging.log4j.core.appender.ConsoleAppender.adoc b/log4j-doc-reference/src/site/Core/org.apache.logging.log4j.core.appender.ConsoleAppender.adoc
new file mode 100644
index 0000000..8ed001e
--- /dev/null
+++ b/log4j-doc-reference/src/site/Core/org.apache.logging.log4j.core.appender.ConsoleAppender.adoc
@@ -0,0 +1,80 @@
+////
+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
+
+ https://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.
+////
+= Console Appender
+
+Appends log events to `System.out` or `System.err` using a layout specified by the user.
+
+== Template
+[source, xml]
+----
+<Console name=""
+ ignoreExceptions="true"
+ bufferedIo="true"
+ bufferSize="${log4j2.encoderByteBufferSize}"
+ immediateFlush="true"
+ target="SYSTEM_OUT"
+ follow="false"
+ direct="false">
+ filter
+ <Property/> (0:n)
+ layout
+</Console>
+----
+
+== Attributes
+
+Required attributes are in **bold face**.
+
+[cols="1,1,1,5m"]
+|===
+|Name
+|Type
+|Default
+|Description
+
+|**name**
+|`String`
+|
+|The name of the appender used in appender references.
+Must be unique.
+
+|ignoreExceptions
+|`boolean`
+|true
+|If set to `false` logging exceptions will be forwarded to the caller.
+
+|bufferedIo
+|`boolean`
+|true
+|If set to `true` (default) the appender will buffer messages before sending them.
+This attribute is ignored if `immediateFlush` is set to `true`.
+
+|bufferSize
+|`int`
+|xref:../Properties/index.adoc#log4j2.encoderByteBufferSize[log4j2.encoderByteBufferSize]
+|Size in bytes of the appender's buffer.
+
+|immediateFlush
+|`boolean`
+|true
+|If set to `true`, the appender flushes the output stream at each message and buffering is disabled regardless of the value of `bufferedIo`.
+
+|target
+|xref:../TypeConverters/index.adoc#org.apache.logging.log4j.core.appender.ConsoleAppender.Target[Target]
+|SYSTEM_OUT
+|Specifies the target of the appender.
+|===
diff --git a/log4j-doc-reference/src/site/Core/org.apache.logging.log4j.core.config.AppendersPlugin.adoc b/log4j-doc-reference/src/site/Core/org.apache.logging.log4j.core.config.AppendersPlugin.adoc
new file mode 100644
index 0000000..2cb3446
--- /dev/null
+++ b/log4j-doc-reference/src/site/Core/org.apache.logging.log4j.core.config.AppendersPlugin.adoc
@@ -0,0 +1,43 @@
+////
+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
+
+ https://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.
+////
+= Appenders
+
+A wrapper element for a list of plugins
+
+== Template
+[source, xml]
+----
+<Appenders>
+ appender (0:n)
+</Appenders>
+----
+
+== Nested Components
+
+[cols="1,1,5m"]
+|===
+|Tag
+|Type
+|Description
+
+|(many)
+|xref:org.apache.logging.log4j.core.Appender.adoc[Appender]
+a|A component that writes events to their final destination, e.g. the console or a file.
+
+Common implementations: xref:org.apache.logging.log4j.core.appender.ConsoleAppender.adoc[ConsoleAppender], xref:org.apache.logging.log4j.core.Appender.adoc[...]
+
+|===
diff --git a/log4j-doc-reference/src/site/Core/org.apache.logging.log4j.core.config.Configuration.adoc b/log4j-doc-reference/src/site/Core/org.apache.logging.log4j.core.config.Configuration.adoc
new file mode 100644
index 0000000..c2518c2
--- /dev/null
+++ b/log4j-doc-reference/src/site/Core/org.apache.logging.log4j.core.config.Configuration.adoc
@@ -0,0 +1,93 @@
+////
+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
+
+ https://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.
+////
+= Configuration
+
+A Log4j 2.x configuration contains many components, two of them `Appenders` and `Loggers` are required.
+
+== Template
+[source, xml]
+----
+<Configuration status="ERROR"
+ dest=""
+ shutdownHook=""
+ shutdownTimeout=""
+ verbose=""
+ name=""
+ strict=""
+ schema=""
+ monitorInterval="0"
+ advertiser="">
+ <Properties/>
+ <Scripts/>
+ <Appenders/>
+ <Loggers/>
+ <CustomLevels/>
+</Configuration>
+----
+
+== Attributes
+
+Required attributes are in **bold face**.
+
+[cols="1,1,1,5m"]
+|===
+|Name
+|Type
+|Default
+|Description
+
+|status
+|xref:../TypeConverters/index.adoc#org.apache.logging.log4j.Level[Level]
+|`ERROR`
+|Sets the level of the status logger.
+
+|name
+|`String`
+|
+|The name of this configuration.
+
+|monitorInterval
+|`int`
+|0
+|Number of seconds between polls for configuration changes.
+|===
+
+== Nested Components
+
+Required components are in **bold face**.
+
+[cols="1,1,5m"]
+|===
+|Tag
+|Type
+|Description
+
+|`Properties`
+|PropertiesPlugin
+|Wrapper element for a list of properties.
+
+If present, this plugin must be the **first** child of the configuration.
+
+|`**Appenders**`
+|xref:org.apache.logging.log4j.core.config.AppendersPlugin.adoc[AppendersPlugin]
+|Wrapper element for a list of xref:org.apache.logging.log4j.core.Appender.adoc[appenders].
+
+|`**Loggers**`
+|LoggersPlugin
+|Wrapper element for a list of logger configurations.
+
+|===
diff --git a/log4j-doc-reference/src/site/Properties/index.adoc b/log4j-doc-reference/src/site/Properties/index.adoc
new file mode 100644
index 0000000..d1e2656
--- /dev/null
+++ b/log4j-doc-reference/src/site/Properties/index.adoc
@@ -0,0 +1,83 @@
+////
+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
+
+ https://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.
+////
+= Log4j Properties
+
+== Custom Property Sources
+
+Properties are located using PropertySources.
+This system is extensible and is enabled through the `PropertySource` interface.
+Additional property source classes can be added through the standard `ServiceLoader` mechanism in Java SE.
+
+
+Properties can be overridden by sources with a lower number priority
+(e.g. -100 comes before 100). The following sources are all available
+by default:
+
+.PropertySource priorities and descriptions
+[cols="2,1,5",frame="all"]
+|===
+|Source |Priority |Description
+
+|Spring Boot Properties
+|-100
+|This property source is enabled only if the Java application uses Spring Boot and the
+`log4j-spring` module is present. It resolves properties using a Spring
+link:https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/env/Environment.html[Environment].
+
+|System Properties
+|0
+|All properties can be set using normal system
+property patterns. These have the lowest numerical priority among commonly available property sources
+and can override included `log4j2.component.properties` files or environment variables. If a `log4j2.system.properties` file is available on the classpath its contents are
+sourced into Java system properties at Log4j startup.
+
+|Environment Variables
+|100
+|Environment variables are all prefixed
+with `LOG4J_`, are in all caps, and words are all separated by
+underscores. Only this naming scheme is support for environment
+variables as there were no old naming schemes to maintain compatibility
+with.
+
+|`log4j2.context.json` or `log4j2.{contextName}.json`
+|110
+|Properties in these files only apply to the specific LoggerContext to which they are bound, either by name or ClassLoader.
+
+|`log4j2.context.properties' or `log4j2.{contextName}.properties`
+|120
+|Properties in these files only apply to the specific LoggerContext to which they are bound, either by name or ClassLoader.
+
+|`log4j2.component.properties` file
+|200
+|Including this file on the classpath can be used as an alternative to providing properties as system
+properties. This is the property source with highest numerical priority and can be used to provide
+default values that can be overridden by the system administrator.
+|===
+
+== Common properties
+
+[cols="1,1,5m"]
+|===
+|Name
+|Default value
+|Description
+
+|[[log4j2.encoderByteBufferSize]]
+`log4j2.encoderByteBufferSize`
+|8192
+|Default size of an appender buffer in bytes.
+|===
diff --git a/log4j-doc-reference/src/site/TypeConverters/index.adoc b/log4j-doc-reference/src/site/TypeConverters/index.adoc
new file mode 100644
index 0000000..4184927
--- /dev/null
+++ b/log4j-doc-reference/src/site/TypeConverters/index.adoc
@@ -0,0 +1,56 @@
+////
+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
+
+ https://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.
+////
+= Type converters
+
+Type converter plugins are used to convert simple `String` values into other types.
+
+== Available converters
+
+[cols="1,2m"]
+|===
+|Type
+|Description
+
+|[[org.apache.logging.log4j.Level]]
+`o.a.l.l.Level`
+a|Represents a logging level.
+A level can be any `String`, the standard ones are:
+
+* `OFF`
+* `FATAL`
+* `ERROR`
+* `WARN`
+* `INFO`
+* `DEBUG`
+* `TRACE`
+
+|[[org.apache.logging.log4j.core.appender.ConsoleAppender.Target]]
+`o.a.l.l.core.appender.ConsoleAppender.Target`
+a|Specifies the target of a console appender. Possible values:
+
+* `SYSTEM_OUT` to log to the standard output,
+* `SYSTEM_ERR` to log to the standard error.
+
+|[[org.apache.logging.log4j.core.Filter.Result]]
+`o.a.l.l.core.Filter.Result`
+a| Possible results for a filter:
+
+* `ACCEPT` accepts a log event unconditionally,
+* `DENY` rejects a log event unconditionally,
+* `NEUTRAL` transfers control to the next filter. If this is the last filter, the message is accepted.
+
+|===
diff --git a/log4j-doc-reference/src/test/resources/log4j-plugins.xml b/log4j-doc-reference/src/test/resources/log4j-plugins.xml
new file mode 100644
index 0000000..ef2ce75
--- /dev/null
+++ b/log4j-doc-reference/src/test/resources/log4j-plugins.xml
@@ -0,0 +1,150 @@
+<?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="http://codehaus-plexus.github.io/MODELLO/1.8.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://codehaus-plexus.github.io/MODELLO/1.8.0 https://codehaus-plexus.github.io/modello/xsd/modello-1.8.0.xsd"
+ xml.namespace="http://logging.apache.org/log4j/2.x/config">
+ <id>log4j-core</id>
+ <name>Log4j Core Plugins</name>
+
+ <classes>
+ <!-- Interfaces -->
+ <class>
+ <name>org.apache.logging.log4j.core.Filter</name>
+ </class>
+ <class>
+ <name>org.apache.logging.log4j.core.Appender</name>
+ </class>
+ <class>
+ <name>org.apache.logging.log4j.core.Layout</name>
+ </class>
+ <class xml.tagName="Appenders" rootElement="true" xsd.compositor="sequence">
+ <name>org.apache.logging.log4j.core.config.AppendersPlugin</name>
+ <fields>
+ <field>
+ <name>appenders</name>
+ <association xml.itemsStyle="flat">
+ <type>org.apache.logging.log4j.core.appender.AbstractAppender</type>
+ <multiplicity>*</multiplicity>
+ </association>
+ </field>
+ </fields>
+ </class>
+ <class java.abstract="true">
+ <name>org.apache.logging.log4j.core.filter.AbstractFilterable</name>
+ <fields>
+ <field>
+ <name>filter</name>
+ <association>
+ <type>org.apache.logging.log4j.core.Filter</type>
+ <multiplicity>1</multiplicity>
+ </association>
+ <description>Filters the log events in this component.</description>
+ </field>
+ <field>
+ <name>propertyArray</name>
+ <association>
+ <type>org.apache.logging.log4j.core.config.Property</type>
+ <multiplicity>*</multiplicity>
+ </association>
+ <description>Additional properties to add to events for this component.</description>
+ </field>
+ </fields>
+ </class>
+ <class java.abstract="true">
+ <name>org.apache.logging.log4j.core.appender.AbstractAppender</name>
+ <superClass>org.apache.logging.log4j.core.filter.AbstractFilterable</superClass>
+ <interfaces>
+ <interface>org.apache.logging.log4j.core.Appender</interface>
+ </interfaces>
+ <fields>
+ <field>
+ <name>ignoreExceptions</name>
+ <type>boolean</type>
+ <defaultValue>true</defaultValue>
+ <description>If set to `false` logging exceptions will be forwarded to the caller.</description>
+ </field>
+ <field>
+ <name>layout</name>
+ <association>
+ <type>org.apache.logging.log4j.core.Layout</type>
+ <multiplicity>1</multiplicity>
+ </association>
+ <description>Specifies the layout used to format log events.</description>
+ </field>
+ <field>
+ <name>name</name>
+ <type>String</type>
+ <required>true</required>
+ <description>Name used to reference this appender. Must be unique</description>
+ </field>
+ </fields>
+ </class>
+ <class java.abstract="true">
+ <name>org.apache.logging.log4j.core.appender.AbstractOutputStreamAppender</name>
+ <superClass>org.apache.logging.log4j.core.appender.AbstractAppender</superClass>
+ <fields>
+ <field>
+ <name>bufferedIo</name>
+ <type>boolean</type>
+ <defaultValue>true</defaultValue>
+ <description>If set to `true`, I/O is buffered.</description>
+ </field>
+ </fields>
+ </class>
+ <class xml.tagName="Console">
+ <name>org.apache.logging.log4j.core.ConsoleAppender</name>
+ <superClass>org.apache.logging.log4j.core.appender.AbstractOutputStreamAppender</superClass>
+ <description>
+ Appends log events to `System.out` or `System.err` using a layout specified by the user.
+ </description>
+ <interfaces>
+ <interface>org.apache.logging.log4j.core.Appender</interface>
+ <interface>org.apache.logging.log4j.core.impl.LocationAware</interface>
+ </interfaces>
+ <fields>
+ <field>
+ <name>immediate</name>
+ <type>boolean</type>
+ <description>If se to `true` buffers are flushed at each </description>
+ <defaultValue>false</defaultValue>
+ </field>
+ </fields>
+ </class>
+
+ <!-- Sub-components -->
+ <class xml.tagName="Property">
+ <name>org.apache.logging.log4j.core.config.Property</name>
+ <description>
+ Represents a key/value pair in the configuration.
+ </description>
+ <fields>
+ <field>
+ <name>key</name>
+ <type>String</type>
+ <description>Key</description>
+ </field>
+ <field>
+ <name>value</name>
+ <type>String</type>
+ <description>Value</description>
+ </field>
+ </fields>
+ </class>
+ </classes>
+</model>
diff --git a/log4j-doc-reference/src/test/resources/log4j.xsd b/log4j-doc-reference/src/test/resources/log4j.xsd
new file mode 100644
index 0000000..6de5b85
--- /dev/null
+++ b/log4j-doc-reference/src/test/resources/log4j.xsd
@@ -0,0 +1,265 @@
+<?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.
+
+-->
+<schema xmlns="http://www.w3.org/2001/XMLSchema"
+ xmlns:log4j="http://logging.apache.org/log4j/2.0/config"
+ xmlns:html="http://www.w3.org/1999/xhtml"
+ targetNamespace="http://logging.apache.org/log4j/2.0/config"
+ elementFormDefault="qualified">
+
+ <element name="Configuration">
+ <annotation>
+ <documentation>
+ <html:p>A Log4j 2.x configuration contains many components, two of them <html:code>Appenders</html:code>
+ and <html:code>Loggers</html:code> are required.</html:p>
+ </documentation>
+ </annotation>
+ <complexType>
+ <sequence>
+ <element name="Appenders" type="log4j:org.apache.logging.log4j.core.config.AppendersPlugin">
+ <annotation>
+ <documentation>
+ Container for a list of appenders.
+ </documentation>
+ </annotation>
+ </element>
+ </sequence>
+ </complexType>
+ </element>
+
+ <!-- Plugins with the same interface -->
+
+ <group name="org.apache.logging.log4j.core.Appender">
+ <choice>
+ <element name="Console" type="log4j:org.apache.logging.log4j.core.appender.ConsoleAppender"/>
+ </choice>
+ </group>
+
+ <group name="org.apache.logging.log4j.core.Filter">
+ <choice>
+ <element name="ThresholdFilter" type="log4j:org.apache.logging.log4j.core.filter.ThresholdFilter"/>
+ </choice>
+ </group>
+
+ <group name="org.apache.logging.log4j.core.Layout">
+ <choice>
+ <element name="PatternLayout" type="log4j:org.apache.logging.log4j.core.layout.PatternLayout"/>
+ </choice>
+ </group>
+
+ <!-- Enums and other simple types -->
+
+ <simpleType name="org.apache.logging.log4j.core.appender.ConsoleAppender.Target">
+ <restriction base="string">
+ <enumeration value="SYSTEM_OUT"/>
+ <enumeration value="SYSTEM_ERR"/>
+ </restriction>
+ </simpleType>
+
+ <simpleType name="org.apache.logging.log4j.core.Filter.Result">
+ <restriction base="string">
+ <enumeration value="ACCEPT"/>
+ <enumeration value="DENY"/>
+ <enumeration value="NEUTRAL"/>
+ </restriction>
+ </simpleType>
+
+ <!-- Plugins -->
+
+ <complexType name="org.apache.logging.log4j.core.config.AppendersPlugin">
+ <sequence>
+ <group ref="log4j:org.apache.logging.log4j.core.Appender" minOccurs="0"/>
+ </sequence>
+ </complexType>
+
+ <complexType name="org.apache.logging.log4j.core.filter.AbstractFilterable">
+ <sequence>
+ <group ref="log4j:org.apache.logging.log4j.core.Filter" minOccurs="0">
+ <annotation>
+ <documentation>
+ A filter to apply to the log events processed by this component.
+ </documentation>
+ </annotation>
+ </group>
+ <element name="Property" type="log4j:org.apache.logging.log4j.core.config.Property" minOccurs="0"
+ maxOccurs="unbounded">
+ <annotation>
+ <documentation>
+ A list of properties to add to the context data of the log event.
+ </documentation>
+ </annotation>
+ </element>
+ </sequence>
+ </complexType>
+
+ <complexType name="org.apache.logging.log4j.core.appender.AbstractAppender">
+ <complexContent>
+ <extension base="log4j:org.apache.logging.log4j.core.filter.AbstractFilterable">
+ <sequence>
+ <group ref="log4j:org.apache.logging.log4j.core.Layout" minOccurs="0">
+ <annotation>
+ <documentation>
+ Specifies the way events are converted into strings.
+ </documentation>
+ </annotation>
+ </group>
+ </sequence>
+ <attribute name="ignoreExceptions" type="boolean" default="true"/>
+ <attribute name="name" type="string" use="required">
+ <annotation>
+ <documentation>The name of the appender.</documentation>
+ </annotation>
+ </attribute>
+ </extension>
+ </complexContent>
+ </complexType>
+
+ <complexType name="org.apache.logging.log4j.core.appender.AbstractOutputStreamAppender">
+ <complexContent>
+ <extension base="log4j:org.apache.logging.log4j.core.appender.AbstractAppender">
+ <attribute name="bufferedIo" type="boolean" default="true">
+ <annotation>
+ <documentation>If set to `true` the appender will buffer events.
+ This is incompatible with `immediateFlush`.
+ </documentation>
+ </annotation>
+ </attribute>
+ <attribute name="bufferSize" type="int">
+ <annotation>
+ <documentation>Size in bytes of the appender's buffer.</documentation>
+ </annotation>
+ </attribute>
+ <attribute name="immediateFlush" type="boolean" default="true">
+ <annotation>
+ <documentation>If set to `true` the output stream will be flushed after each event.
+ </documentation>
+ </annotation>
+ </attribute>
+ </extension>
+ </complexContent>
+ </complexType>
+
+ <complexType name="org.apache.logging.log4j.core.appender.ConsoleAppender">
+ <annotation>
+ <documentation>
+ <html:p>Appends log events to <html:code>System.out</html:code> or <html:code>System.err</html:code> using
+ a layout specified by the user.
+ </html:p>
+ </documentation>
+ </annotation>
+ <complexContent>
+ <extension base="log4j:org.apache.logging.log4j.core.appender.AbstractOutputStreamAppender">
+ <attribute name="target" type="log4j:org.apache.logging.log4j.core.appender.ConsoleAppender.Target"
+ default="SYSTEM_OUT">
+ <annotation>
+ <documentation>Specifies the target of the console appender.</documentation>
+ </annotation>
+ </attribute>
+ <attribute name="follow" type="boolean" default="false">
+ <annotation>
+ <documentation>If set to `true`, the appender follows redirections performed using
+ `System#setOut()/setErr()`.
+ </documentation>
+ </annotation>
+ </attribute>
+ <attribute name="direct" type="boolean" default="false">
+ <annotation>
+ <documentation>If set to `true`, the appender uses the `FileDescriptor.out/err` descriptors
+ directly.
+ </documentation>
+ </annotation>
+ </attribute>
+ </extension>
+ </complexContent>
+ </complexType>
+
+ <complexType name="org.apache.logging.log4j.core.filter.AbstractFilter">
+ <attribute name="onMatch" type="log4j:org.apache.logging.log4j.core.Filter.Result" default="NEUTRAL">
+ <annotation>
+ <documentation>The result to return when the filter matches.</documentation>
+ </annotation>
+ </attribute>
+ <attribute name="onMismatch" type="log4j:org.apache.logging.log4j.core.Filter.Result" default="DENY">
+ <annotation>
+ <documentation>The result to return when the filter does not match.</documentation>
+ </annotation>
+ </attribute>
+ </complexType>
+
+ <complexType name="org.apache.logging.log4j.core.filter.ThresholdFilter">
+ <annotation>
+ <documentation>
+ This filter returns the `onMatch` result if the level in the `LogEvent` is the same or more specific
+ than the configured level and the `onMismatch` value otherwise.
+ For example, if the `ThresholdFilter` is configured with Level `ERROR` and the `LogEvent` contains Level
+ `DEBUG` then the `onMismatch` value will be returned since `ERROR` events are more specific than
+ `DEBUG`.
+ </documentation>
+ </annotation>
+ <simpleContent>
+ <extension base="log4j:org.apache.logging.log4j.core.filter.AbstractFilter">
+ <attribute name="level" type="string" default="ERROR">
+ <annotation>
+ <documentation>The threshold level.</documentation>
+ </annotation>
+ </attribute>
+ </extension>
+ </simpleContent>
+ </complexType>
+
+ <complexType name="org.apache.logging.log4j.core.layout.PatternLayout">
+ <annotation>
+ <documentation>
+ <html:h1>
+ A flexible layout configurable with pattern string.
+ </html:h1>
+ <html:p>
+ 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 <html:em>conversion pattern</html:em>.
+ </html:p>
+ <html:p>
+ 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 <html:em>conversion specifiers</html:em>.
+ </html:p>
+ </documentation>
+ </annotation>
+ <attribute name="pattern" default="%m%n">
+ <annotation>
+ <documentation>The pattern to use to format log events.</documentation>
+ </annotation>
+ </attribute>
+ </complexType>
+
+ <complexType name="org.apache.logging.log4j.core.config.Property">
+ <annotation>
+ <documentation>Represents a key/value pair in the configuration.</documentation>
+ </annotation>
+ <attribute name="key" type="string" use="required">
+ <annotation>
+ <documentation>The key.</documentation>
+ </annotation>
+ </attribute>
+ <attribute name="value" type="string" use="required">
+ <annotation>
+ <documentation>The value.</documentation>
+ </annotation>
+ </attribute>
+ </complexType>
+</schema>
\ No newline at end of file
diff --git a/pom.xml b/pom.xml
index f339d88..c0b30bb 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-doc-reference</module>
</modules>