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 <[email protected]> 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 <[email protected]> --- .../.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].
