This is an automated email from the ASF dual-hosted git repository. pkarwasz pushed a commit to branch 2.x-site-pro in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 2a9a38015ca7449b2715e9886bd92ea66d85b2a8 Author: Piotr P. Karwasz <[email protected]> AuthorDate: Mon Oct 21 11:14:25 2024 +0200 Improve documentation of `2.24.0` bridge changes --- src/changelog/2.24.0/.release-notes.adoc.ftl | 5 +++++ .../modules/ROOT/pages/migrate-from-log4j1.adoc | 22 +++++++++++++--------- .../systemproperties/properties-log4j-12-api.adoc | 14 +++++++++----- 3 files changed, 27 insertions(+), 14 deletions(-) diff --git a/src/changelog/2.24.0/.release-notes.adoc.ftl b/src/changelog/2.24.0/.release-notes.adoc.ftl index 3be76ceb6b..affbbf4458 100644 --- a/src/changelog/2.24.0/.release-notes.adoc.ftl +++ b/src/changelog/2.24.0/.release-notes.adoc.ftl @@ -40,6 +40,11 @@ The xref:index.adoc[Apache Log4j 2] website has been almost entirely rewritten t The JUL-to-Log4j API and Log4j 1-to-Log4j API will no longer be able to modify the configuration of Log4j Core by default. If such a functionality is required, it must be explicitly enabled. +See the documentation of the +xref:migrate-from-log4j1.adoc#log4j1.compatibility[`log4j1.compatibility`] +and +xref:log4j-jul.adoc#log4j2.julLoggerAdapter[`log4j2.julLoggerAdapter`] +configuration properties for more details. === Modules diff --git a/src/site/antora/modules/ROOT/pages/migrate-from-log4j1.adoc b/src/site/antora/modules/ROOT/pages/migrate-from-log4j1.adoc index 90c4597806..0f2835d945 100644 --- a/src/site/antora/modules/ROOT/pages/migrate-from-log4j1.adoc +++ b/src/site/antora/modules/ROOT/pages/migrate-from-log4j1.adoc @@ -487,8 +487,8 @@ If an exact backward compatibility is required, you need to <<log4j-1-2-api-inst [#ConfigurationCompatibility] === Use Log4j 1 to Log4j 2 bridge -If you can not convert your configuration files from Log4j 1 to Log4j 2, the Log4j 1 to Log4j 2 bridge can convert your configuration files at runtime. -In order to use this feature you need to <<log4j-1-2-api-installation,Install the Log4j 1 to Log4j 2 bridge>> and set one of the following configuration properties: +If you cannot convert your configuration files from Log4j 1 to Log4j 2, the Log4j 1 to Log4j 2 bridge can convert your configuration files at runtime. +To use this feature, you need to <<log4j-1-2-api-installation,Install the Log4j 1 to Log4j 2 bridge>> and set one of the following configuration properties: include::partial$manual/systemproperties/properties-log4j-12-api.adoc[leveloffset=+2] @@ -540,13 +540,17 @@ xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-1-2-api_org-apache-log [#option-1-use-the-log4j-1-x-bridge-log4j-1-2-api] == [[Log4j12Bridge]]Log4j 1 to Log4j 2 bridge -In order to help users with the migration process, a Log4j 1 to Log4j 2 bridge is available. -The bridge can fulfill three separate functions: - -* it forwards all <<log4j-1-api-methods,Log4j 1 API>> method calls to the corresponding Log4j 2 API calls, -* since version 2.17.2 is supports the usage of some components written for Log4j 1 inside Log4j 2 Core, -* it provides a limited support for programmatic configuration of Log4j 2 Core, using Log4j 1 method calls, -* it provides a limited support for Log4j 1 configuration file formats. +To help users with the migration process, a Log4j 1 to Log4j 2 bridge is available. +The bridge can fulfill four separate functions: + +* It forwards all <<log4j-1-api-methods,Log4j 1 API>> method calls to the Log4j 2 API. +See <<api-use-bridge,how to use the bridge for Log4j 1 API migration>> for more details. +* Since version 2.17.2 the bridge supports the usage of some components written for Log4j 1 inside Log4j 2 Core. +See <<migrate-custom-components,how to use the bridge for Log4j 1 Backend migration>> for more details. +* It provides limited support for programmatic configuration of Log4j 2 Core, using Log4j 1 method calls. +This functionality requires the <<log4j1.compatibility,`log4j1.compatibility` configuration property>> to be set to `true`. +* It provides a limited support for Log4j 1 configuration file formats. +See <<ConfigurationCompatibility,how to use the bridge for Log4j 1 Configuration file migration>> for more details. [#log4j-1-2-api-installation] === Installation diff --git a/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-log4j-12-api.adoc b/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-log4j-12-api.adoc index 9fbbdf9d38..4a8e9550be 100644 --- a/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-log4j-12-api.adoc +++ b/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-log4j-12-api.adoc @@ -24,12 +24,16 @@ | Default value | `false` |=== -If set to `true`, Log4j 2 will scan the classpath to find Log4j 1 configuration files in the following standard locations: +If set to `true`, Log4j 2 will: -* `log4j-test.properties`, -* `log4j-test.xml`, -* `log4j.properties`, -* `log4j.xml`. +* Scan the classpath to find Log4j 1 configuration files in the following standard locations: + +** `log4j-test.properties`, +** `log4j-test.xml`, +** `log4j.properties`, +** `log4j.xml`. + +* (since `2.24.0`) Enable the usage of the `o.a.log4j.PropertyConfigurator` and `o.a.log4j.xml.DOMConfigurator` classes in your code. [id=log4j.configuration] == `log4j.configuration`
