[logging-log4j-site] branch asf-site updated: Add new "When to use this the Log4j 1.x bridge" section to migration doc (#629)

[vy...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

vy pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/logging-log4j-site.git


The following commit(s) were added to refs/heads/asf-site by this push:
     new 839a83c  Add new "When to use this the Log4j 1.x bridge" section to migration doc (#629)
839a83c is described below

commit 839a83ceb76b128246fca9fc99a50b7c25499350
Author: Volkan Yazıcı <vo...@yazi.ci>
AuthorDate: Tue Dec 14 23:06:56 2021 +0100

    Add new "When to use this the Log4j 1.x bridge" section to migration doc (#629)
---
 log4j-2.16.0/log4j-1.2-api/index.html |  2 +-
 log4j-2.16.0/manual/migration.html    | 15 +++++++++++++++
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/log4j-2.16.0/log4j-1.2-api/index.html b/log4j-2.16.0/log4j-1.2-api/index.html
index 53f0c45..fc491c1 100644
--- a/log4j-2.16.0/log4j-1.2-api/index.html
+++ b/log4j-2.16.0/log4j-1.2-api/index.html
@@ -223,7 +223,7 @@
 <td> Reconfigures Log4j 2                 </td></tr>
 </tbody>
 </table>
-<p>If log4j-core is not present location information will not be accurate in calls using the Log4j 1.2 API. The config package which attempts tp convert Log4j 1.x configurations to Log4j 2 is not supported without Log4j 2.</p>
+<p>If log4j-core is not present location information will not be accurate in calls using the Log4j 1.2 API. The config package which attempts to convert Log4j 1.x configurations to Log4j 2 is not supported without Log4j 2.</p>
 <p>For more information, see <a href="../runtime-dependencies.html">Runtime Dependencies</a>.</p></section><section>
 <h2><a name="Usage"></a>Usage</h2>
 <p>To use the Log4j Legacy Bridge just remove all the Log4j 1.x jars from the application and replace them with the bridge jar. Once in place all logging that uses Log4j 1.x will be routed to Log4j 2. However, applications that attempt to modify legacy Log4j by adding Appenders, Filters, etc may experience problems if they try to verify the success of these actions as these methods are largely no-ops.</p></section>
diff --git a/log4j-2.16.0/manual/migration.html b/log4j-2.16.0/manual/migration.html
index 4264ab2..2e7c7ce 100644
--- a/log4j-2.16.0/manual/migration.html
+++ b/log4j-2.16.0/manual/migration.html
@@ -146,6 +146,21 @@
 <h2><a name="Migrating_from_Log4j_1.x"></a>Migrating from Log4j 1.x</h2>
           <a name="Log4j1.2Bridge"></a>
           <section>
+            <h3><a name="When_to_use_this_the_Log4j_1.x_bridge"></a>When to use this the Log4j 1.x bridge</h3>
+            <p>
+              This bridge is useful as a dependency of an "application" which would like to use Log4j v2 as its main logging framework, if either that application itself hasn't been changed from using the Log4j 1.x API to the 1.x API, or if such an application depends on one or several (perhaps old) libraries that are "out of your control", and which themselves still contain code and thus a compile dependency on Log 1.x only.
+            </p>
+            <p>
+              Once you have migrated all of your own application &amp; library code under your control, you may not need this bridge.
+              Note that when you use a library/framework that can be configured to use several logging frameworks, then you typically don't need this bridge either anymore, as you may be able to directly configure it to use Log4j v2 instead v1.
+              Some libraries/frameworks even auto-detect the presence of certain logging framework implementations on their classpath, and automagically switch their internal logging delegation accordingly; try simple removing the Log4j v1 dependency instead of replacing it with this bridge, and test if logging from all of your dependencies still work.
+            </p>
+            <p>
+              If you own or can contribute open source to the library you depend on, then you likely would prefer replacing its use of the Log4j v1 Logging API with the v2 API.
+              (It typically does not make sense for libraries to depend on this bridge and support both the v1 and v2 Log4j API, because end-users of such a library would still have to replace their Log4j configuration v1 with a different v2 config anyway; see below.)
+            </p>
+          </section>
+          <section>
 <h3><a name="Using_the_Log4j_1.x_bridge"></a>Using the Log4j 1.x bridge</h3>
             
 <p>