This is an automated email from the ASF dual-hosted git repository. pkarwasz pushed a commit to branch doc/2.x/mongodb in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit b17986d7882fe54f9a4227d385e66278286c6ec0 Author: Piotr P. Karwasz <[email protected]> AuthorDate: Mon May 27 21:29:41 2024 +0200 Refactor MongoDB documentation We refactor MongoDB documentation by: * adding a section of "Appenders" to help users choose the right module for their MongoDB Java driver, * removing the legacy `log4j-mongodb3.html` and `log4j-mongodb4.html` pages. --- src/site/antora/modules/ROOT/nav.adoc | 2 - .../antora/modules/ROOT/pages/log4j-mongodb3.adoc | 46 ----------- .../antora/modules/ROOT/pages/log4j-mongodb4.adoc | 44 ----------- .../modules/ROOT/pages/manual/appenders.adoc | 90 ++++++++++++++++++---- src/site/resources/.htaccess | 6 +- 5 files changed, 79 insertions(+), 109 deletions(-) diff --git a/src/site/antora/modules/ROOT/nav.adoc b/src/site/antora/modules/ROOT/nav.adoc index 65d5a8bb34..36bf051a9b 100644 --- a/src/site/antora/modules/ROOT/nav.adoc +++ b/src/site/antora/modules/ROOT/nav.adoc @@ -65,8 +65,6 @@ .Components * xref:log4j-flume-ng.adoc[] -* xref:log4j-mongodb3.adoc[] -* xref:log4j-mongodb4.adoc[] * xref:log4j-iostreams.adoc[] * xref:log4j-docker.adoc[] * xref:log4j-spring-cloud-config-client.adoc[] diff --git a/src/site/antora/modules/ROOT/pages/log4j-mongodb3.adoc b/src/site/antora/modules/ROOT/pages/log4j-mongodb3.adoc deleted file mode 100644 index 4249b5e04b..0000000000 --- a/src/site/antora/modules/ROOT/pages/log4j-mongodb3.adoc +++ /dev/null @@ -1,46 +0,0 @@ -//// -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. -//// - -// TODO: use properties for dynamic dependency versions - -= MongoDB 3 appender - -http://www.mongodb.org/[MongoDB] is supported through the http://docs.mongodb.org/ecosystem/drivers/java/[Java MongoDB Driver]. - -[source,xml] ----- - <dependencyManagement> - <dependencies> - <dependency> - <groupId>org.mongodb</groupId> - <artifactId>mongo-java-driver</artifactId> - <version>3.12.11</version> - </dependency> - </dependencies> - </dependencyManagement> - <dependencies> - <dependency> - <groupId>org.mongodb</groupId> - <artifactId>mongo-java-driver</artifactId> - </dependency> - </dependencies> ----- - -== Requirements - -The MongoDB Appender is dependent on the Log4j 2 API and implementation. -For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies]. diff --git a/src/site/antora/modules/ROOT/pages/log4j-mongodb4.adoc b/src/site/antora/modules/ROOT/pages/log4j-mongodb4.adoc deleted file mode 100644 index fe7eab9861..0000000000 --- a/src/site/antora/modules/ROOT/pages/log4j-mongodb4.adoc +++ /dev/null @@ -1,44 +0,0 @@ -//// -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. -//// - -= MongoDB 4 appender - -http://www.mongodb.org/[MongoDB] is supported through the http://docs.mongodb.org/ecosystem/drivers/java/[Java MongoDB Driver]. - -[source,xml] ----- - <dependencyManagement> - <dependencies> - <dependency> - <groupId>org.mongodb</groupId> - <artifactId>mongo-java-driver</artifactId> - <version>4.5.0</version> - </dependency> - </dependencies> - </dependencyManagement> - <dependencies> - <dependency> - <groupId>org.mongodb</groupId> - <artifactId>mongo-java-driver</artifactId> - </dependency> - </dependencies> ----- - -== Requirements - -The MongoDB Appender is dependent on the Log4j 2 API and implementation. -For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies]. diff --git a/src/site/antora/modules/ROOT/pages/manual/appenders.adoc b/src/site/antora/modules/ROOT/pages/manual/appenders.adoc index 8d01cbc73a..da5cf0ab53 100644 --- a/src/site/antora/modules/ROOT/pages/manual/appenders.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/appenders.adoc @@ -1904,21 +1904,81 @@ The following example demonstrates how log events are persisted in NoSQL databas } ---- -[#NoSQLAppenderMongoDBMain] -== NoSQL Appenders for MongoDB +[#NoSQLAppenderMongoDB] +=== NoSQL providers for MongoDB -Starting with Log4 2.11.0, we provide the following MongoDB modules: +[#mongo-installation] +==== Installation -* Added in 2.11.0, removed in 2.14.0: `log4j-mongodb2` defines the configuration element MongoDb2 matching the MongoDB Driver version 2. -* Added in 2.11.0, removed in 2.24.0: `log4j-mongodb3` defines the configuration element MongoDb3 matching the MongoDB Driver version 3. -* Added in 2.14.0, deprecated in 2.24.0: `log4j-mongodb4` defines the configuration element -link:#NoSQLAppenderMongoDB4[`MongoDb4`] matching the MongoDB Driver version 4. -* Added in 2.24.0: `log4j-mongodb` defines the configuration element -link:#NoSQLAppenderMongoDBCurrent[`MongoDb`] matching the current MongoDB Driver (version 5). -This module tracks the current MongoDB Driver. +Starting with version 2.11.0, Log4j supplies providers for the +https://www.mongodb.com/[MongoDB] +NoSQL database engine, based on the +https://www.mongodb.com/docs/drivers/java/sync/current/[MongoDB synchronous Java driver]. +The choice of the provider to user depends on: -[#NoSQLAppenderMongoDBCurrent] -== NoSQL Appender for MongoDB +* the major version of the MongoDB Java driver your application uses: Log4j supports all major versions starting from version 2. +* the type of driver API used: either the _Legacy API_ or the _Modern API_. +See https://www.mongodb.com/docs/drivers/java/sync/current/legacy/[MongoDB documentation] +for the difference between APIs. + +[NOTE] +==== +The list of dependencies of your application provides a hint as to which driver API your application is using. +If your application contains any one of these dependencies, it might use the **Legacy API**: + +* `org.mongodb:mongo-java-driver` +* `org.mongodb:mongodb-driver-legacy` + +If you application only uses `org.mongodb:mongodb-driver-sync`, it uses the **Modern API**. +==== + +[CAUTION] +==== +The version of the MongoDB Java driver is not the same as the version of the MongoDB server. +See +https://www.mongodb.com/docs/drivers/java/sync/current/compatibility/[MongoDB compatibility matrix] +for more information. +==== + +In order to use a Log4j MongoDB appender you need to add the following dependencies to your application: + +.MongoDB providers compatibility table +[cols="2,2,2,5"] +|=== +| Driver version | Driver API | Log4j artifact | Notes + +| `2.x` +| Legacy +| https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-mongodb2[`log4j-mongodb2`] +| Reached end-of-support. + +Last released version: `2.12.4` + +| [[NoSQLAppenderMongoDB3]]`3.x` +| Legacy +| https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-mongodb3[`log4j-mongodb3`] +| Reached end-of-support. + +Last released version: `2.23.1` + +| `4.x` +| Modern +| https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-mongodb4[`log4j-mongodb4`] +| + +| `5.x` or later +| Modern +| https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-mongodb[`log4j-mongodb`] +| +|=== + +[TIP] +==== +If you are note sure, which implementation to choose, `log4j-mongodb` is the recommended choice. +==== + +[#log4j-mongodb] +==== NoSQL provider for MongoDB (current) This section details specializations of the link:#NoSQLAppender[NoSQLAppender] provider for MongoDB using the current MongoDB driver (version 5). @@ -2006,10 +2066,10 @@ You can define additional fields to log using KeyValuePair elements, for example </Configuration> ---- -[#NoSQLAppenderMongoDB4] -== (Deprecated) No SQLAppender for MongoDB 4 +[#log4j-mongodb4] +==== [[NoSQLAppenderMongoDB4]] NoSQL provider for MongoDB 4 (deprecated) -The `log4j-mongodb4` module is deprecated in favor of link:#NoSQLAppenderMongoDBCurrent[NoSQLAppender for MongoDB]. +The `log4j-mongodb4` module is deprecated in favor of link:#log4j-mongodb[NoSQL provider for MongoDB]. This section details specializations of the link:#NoSQLAppender[NoSQLAppender] provider for MongoDB using the MongoDB driver version 4. The NoSQLAppender Appender writes log events to a NoSQL database using an internal lightweight provider interface. diff --git a/src/site/resources/.htaccess b/src/site/resources/.htaccess index 47f907b75d..965a0a215e 100644 --- a/src/site/resources/.htaccess +++ b/src/site/resources/.htaccess @@ -33,6 +33,8 @@ RewriteRule "^(.+)$" "$1.html" # The content moved between pages RewriteRule "^log4j-core/apidocs(.*)$" "javadoc/log4j-core$1" [R=permanent] +RewriteRule "^log4j-mongodb3\.html$" "manual/appenders.html#NoSQLAppenderMongoDB" [R=permanent] +RewriteRule "^log4j-mongodb4\.html$" "manual/appenders.html#log4j-mongodb4" [R=permanent] RewriteRule "^manual/api-separation\.html$" "manual/api.html" [R=permanent] RewriteRule "^manual/scala-api\.html$" "/log4j/scala/index.html" [R=permanent] RewriteRule "^manual/usage\.html$" "manual/api.html" [R=permanent] @@ -59,8 +61,8 @@ RewriteRule "^log4j-jcl\.html/index\.html$" "log4j-jcl.html" [R=permanent] RewriteRule "^log4j-jmx-gui\.html/index\.html$" "log4j-jmx-gui.html" [R=permanent] RewriteRule "^log4j-jpl\.html/index\.html$" "log4j-jpl.html" [R=permanent] RewriteRule "^log4j-jul\.html/index\.html$" "log4j-jul.html" [R=permanent] -RewriteRule "^log4j-mongodb3\.html/index\.html$" "log4j-mongodb3.html" [R=permanent] -RewriteRule "^log4j-mongodb4\.html/index\.html$" "log4j-mongodb4.html" [R=permanent] +RewriteRule "^log4j-mongodb3\.html/index\.html$" "manual/appenders.html#NoSQLAppenderMongoDB" [R=permanent] +RewriteRule "^log4j-mongodb4\.html/index\.html$" "manual/appenders.html#log4j-mongodb4" [R=permanent] RewriteRule "^log4j-slf4j-impl\.html/index\.html$" "log4j-slf4j-impl.html" [R=permanent] RewriteRule "^log4j-slf4j2-impl\.html/index\.html$" "log4j-slf4j2-impl.html" [R=permanent] RewriteRule "^log4j-spring-boot\.html/index\.html$" "log4j-spring-boot.html" [R=permanent]
