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 2026/06/27 12:12:33 UTC
(logging-log4j2) 03/03: Document `Path` or `URI` location resolution and add changelog entry
This is an automated email from the ASF dual-hosted git repository.
ppkarwasz pushed a commit to branch feat/2.x/uniform-uri-conversion
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit c78318271a21785c7cb23c6ae970a180765fdada
Author: Piotr P. Karwasz <pk...@apache.org>
AuthorDate: Sat Jun 27 14:07:46 2026 +0200
Document `Path` or `URI` location resolution and add changelog entry
Add a reusable `path-or-uri.adoc` partial describing how a location given
as a file path or a URI is resolved (absolute URI as-is, absolute path to a
`file:` URI, relative path to a file or class path resource), and include it
in the `log4j2.configurationFile` system property documentation, replacing
the narrower relative-only description and fixing its broken transport
security cross-reference.
Also present the automatically scanned configuration locations as
`classpath:` URIs in the `AutomaticConfiguration` section, since they are
class path resources rather than file system paths.
Add a changelog entry for the behavioral change. The issue reference is left
out on purpose and will be set to the PR number.
Assisted-By: Claude Opus 4.8 <no...@anthropic.com>
---
.../.2.x.x/uniform_path_uri_resolution.xml | 11 ++++++++
.../modules/ROOT/pages/manual/configuration.adoc | 12 +++++----
.../modules/ROOT/partials/manual/path-or-uri.adoc | 31 ++++++++++++++++++++++
.../properties-configuration-factory.adoc | 7 +----
4 files changed, 50 insertions(+), 11 deletions(-)
diff --git a/src/changelog/.2.x.x/uniform_path_uri_resolution.xml b/src/changelog/.2.x.x/uniform_path_uri_resolution.xml
new file mode 100644
index 0000000000..2d3a983806
--- /dev/null
+++ b/src/changelog/.2.x.x/uniform_path_uri_resolution.xml
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<entry xmlns="https://logging.apache.org/xml/ns"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ https://logging.apache.org/xml/ns
+ https://logging.apache.org/xml/ns/log4j-changelog-0.xsd"
+ type="changed">
+ <description format="asciidoc">
+ Configuration locations provided as a file path or `URI` are now handled consistently across operating systems.
+ </description>
+</entry>
\ No newline at end of file
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
index 3b64deb3cb..102a93670f 100644
--- a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
@@ -28,12 +28,14 @@ If you are looking for a quick start on using Log4j in your application or libra
[id=automatic-configuration]
== [[AutomaticConfiguration]] Configuration file location
-Upon initialization of a new xref:manual/architecture.adoc#LoggerContext[logger context, the anchor of the logging implementation], Log4j Core assigns it a context name and scans the following **classpath** locations for a configuration file in following order:
+Upon initialization of a new xref:manual/architecture.adoc#LoggerContext[logger context, the anchor of the logging implementation], Log4j Core assigns it a context name and scans the **classpath** for a configuration file at the following locations, in order:
-. Files named `log4j2-test<contextName>.<extension>`
-. Files named `log4j2-test.<extension>`
-. Files named `log4j2<contextName>.<extension>`
-. Files named `log4j2.<extension>`
+. `classpath:log4j2-test<contextName>.<extension>`
+. `classpath:log4j2-test.<extension>`
+. `classpath:log4j2<contextName>.<extension>`
+. `classpath:log4j2.<extension>`
+
+These locations are class path resources: a configuration file of the same name placed in the working directory is **not** loaded automatically.
The `<contextName>` and `<extension>` placeholders above have the following meaning
diff --git a/src/site/antora/modules/ROOT/partials/manual/path-or-uri.adoc b/src/site/antora/modules/ROOT/partials/manual/path-or-uri.adoc
new file mode 100644
index 0000000000..cfce6eec1c
--- /dev/null
+++ b/src/site/antora/modules/ROOT/partials/manual/path-or-uri.adoc
@@ -0,0 +1,31 @@
+////
+ 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.
+////
+
+Such a location is given as either a file system
+https://docs.oracle.com/javase/{java-target-version}/docs/api/java/nio/file/Path.html[path]
+or a
+https://docs.oracle.com/javase/{java-target-version}/docs/api/java/net/URI.html[`URI`],
+and is resolved as follows:
+
+* An **absolute URI**, that is one carrying a scheme such as `file:`, `https:` or `classpath:`, is used as provided.
+Absolute URIs whose scheme is not `classpath:` are subject to the
+xref:manual/systemproperties.adoc#properties-transport-security[transport security] restrictions.
+
+* An **absolute file path** for the current operating system (for example `/var/log4j2.xml` on UNIX, or
+`C:\log4j2.xml` and `C:/log4j2.xml` on Windows) is resolved to a local file.
+
+* A **relative path** is resolved to a local file if that file exists, or to a class path resource otherwise.
diff --git a/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-configuration-factory.adoc b/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-configuration-factory.adoc
index 1841a4ee4d..cdcdceecd6 100644
--- a/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-configuration-factory.adoc
+++ b/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-configuration-factory.adoc
@@ -42,12 +42,7 @@ Log4j will attempt to use the provided configuration factory before any other fa
Specifies a comma-separated list of URIs or file paths to Log4j 2 configuration files.
-If a relative URL is provided, it is interpreted as:
-
-* path to a file, if the file exists,
-* a classpath resource otherwise.
-
-Usage of absolute URLs is restricted by the xref:manual/configuration.adoc#properties-transport-security[Transport Security] configuration options.
+include::partial$manual/path-or-uri.adoc[]
See also xref:manual/configuration.adoc#AutomaticConfiguration[Automatic Configuration].