Add getConfiguration method for multiple URIs #3921

yybmion · 2025-09-08T10:53:00Z

Summary

Adds a new public API to ConfigurationFactory for creating configurations
from multiple URIs, automatically combining them into a CompositeConfiguration when needed.

Motivation

External frameworks like Spring Boot currently need to understand Log4j's internal implementation to create composite configurations. This new API encapsulates that complexity.

Addresses feedback from #3839

✅ Required checks

License: I confirm that my changes are submitted under the Apache License, Version 2.0.
Commit signatures: All commits are signed and verifiable. (See GitHub Docs on Commit Signature Verification).
Code formatting: The code is formatted according to the project’s style guide.
How to check and fix formatting
- To check formatting: ./mvnw spotless:check
- To fix formatting: ./mvnw spotless:apply
See the build instructions for details.
Build & Test: I verified that the project builds and all unit tests pass.

How to build the project

Run: ./mvnw verify

See the build instructions for details.

🧪 Tests (select one)

I have added or updated tests to cover my changes.
No additional tests are needed for this change.

📝 Changelog (select one)

I added a changelog entry in src/changelog/.2.x.x. (See Changelog Entry File Guide).
This is a trivial change and does not require a changelog entry.

log4j-core/src/main/java/org/apache/logging/log4j/core/config/ConfigurationFactory.java

yybmion · 2025-09-26T09:41:48Z

Thanks for the review, @vy. I've updated the PR.

If this looks good, I'll proceed with adding tests and changelog.

vy · 2025-09-26T09:43:49Z

If this looks good, I'll proceed with adding tests and changelog.

@yybmion, yes, please proceed with tests and a changelog.

yybmion · 2025-09-26T14:25:16Z

@yybmion, yes, please proceed with tests and a changelog.

@vy , Added tests and changelog as requested.

...j-core-test/src/test/java/org/apache/logging/log4j/core/config/ConfigurationFactoryTest.java

log4j-core/src/main/java/org/apache/logging/log4j/core/config/json/package-info.java

log4j-core/src/main/java/org/apache/logging/log4j/core/config/properties/package-info.java

log4j-core/src/main/java/org/apache/logging/log4j/core/config/xml/package-info.java

log4j-core/src/main/java/org/apache/logging/log4j/core/config/yaml/package-info.java

src/changelog/.2.x.x/add_getConfiguration_method_for_mulitiple_URIs.xml

yybmion · 2025-10-03T14:20:52Z

Thanks for the review @vy, Changes applied as requested.

Added a null element check in the URI list to throw a ConfigurationException when any element is null. This ensures that testGetConfigurationWithNullInList passes.

for (final URI uri : uris) {

     if (uri == null) {
          throw new ConfigurationException("URI list contains null element");
   }
...

vy

@yybmion, thanks so much for your patience. I am happy with the last state of the PR.

@ppkarwasz, do you any remarks?

log4j-core/src/main/java/org/apache/logging/log4j/core/config/json/package-info.java

github-actions · 2025-10-03T16:44:49Z

Job	Requested goals	Build Tool Version	Build Outcome
build-macos-latest	clean install	3.9.8	✅
build-ubuntu-latest	clean install	3.9.8	✅
build-windows-latest	clean install	3.9.8	✅

Generated by gradle/develocity-actions

yybmion · 2025-10-03T17:44:20Z

@vy, I'm sorry about the confusion. Previously, I bumped the versions of those packages in the last PR (#3839) after making some changes, but I forgot to revert them. I've now restored them to their original values.

vy · 2025-10-10T08:04:58Z

@yybmion, CI builds are failing. Would you mind reading the Log4j Development Guide and resolving all build failures, please?

yybmion · 2025-10-10T08:46:07Z

@yybmion, just a sec, why do we need these version bumps? We did not touch to these packages.

@vy I think the version bumps are actually needed because the new public method in ConfigurationFactory is inherited by all its subclasses (JsonConfigurationFactory, XmlConfigurationFactory, etc.), which adds the method to those packages' public API.

This is causing the build failure. I've updated the versions back to 2.26.0.

ppkarwasz

Hi @yybmion,

Thanks for the PR, and apologies for the delayed feedback: I haven’t had as much time to spend on Log4j recently as I’d like.

I like the direction of your change, but there are still a few edge cases we need to address.

In particular, I expected the PR to integrate the newly introduced method into the existing code.

For example, ConfigurationFactory.Factory#getConfiguration(LoggerContext, String, URI) could benefit from using it: we currently have a couple of legacy mechanisms for passing multiple URIs through a single URI parameter:

If uri == null, the log4j2.configurationFile property is treated as a comma-separated list of file paths or URIs.
If uri != null, there’s a legacy (and admittedly hacky) method of cramming two URIs into one string (see parseConfigLocations), which unfortunately still needs to be supported.

These mechanisms are handled in getConfiguration(LoggerContext, String, URI), but I think we should delegate them to the newly introduced method.

log4j-core/src/main/java/org/apache/logging/log4j/core/config/ConfigurationFactory.java

...j-core-test/src/test/java/org/apache/logging/log4j/core/config/ConfigurationFactoryTest.java

ppkarwasz · 2025-10-10T09:49:31Z

I realize my comments go a bit beyond the immediate scope of this PR, but the section of code below has become a real maintenance headache. It would be great if we could take the opportunity to clean it up once and for all:

logging-log4j2/log4j-core/src/main/java/org/apache/logging/log4j/core/config/ConfigurationFactory.java

Lines 373 to 478 in 8a3fb53

    
           public Configuration getConfiguration( 
        
                   final LoggerContext loggerContext, final String name, final URI configLocation) { 
        
               if (configLocation == null) { 
        
                   final String configLocationStr = this.substitutor.replace( 
        
                           PropertiesUtil.getProperties().getStringProperty(CONFIGURATION_FILE_PROPERTY)); 
        
                   if (configLocationStr != null) { 
        
                       final String[] sources = parseConfigLocations(configLocationStr); 
        
                       if (sources.length > 1) { 
        
                           final List<AbstractConfiguration> configs = new ArrayList<>(); 
        
                           for (final String sourceLocation : sources) { 
        
                               final Configuration config = getConfiguration(loggerContext, sourceLocation.trim()); 
        
                               if (config != null) { 
        
                                   if (config instanceof AbstractConfiguration) { 
        
                                       configs.add((AbstractConfiguration) config); 
        
                                   } else { 
        
                                       LOGGER.error("Failed to created configuration at {}", sourceLocation); 
        
                                       return null; 
        
                                   } 
        
                               } else { 
        
                                   LOGGER.warn("Unable to create configuration for {}, ignoring", sourceLocation); 
        
                               } 
        
                           } 
        
                           if (configs.size() > 1) { 
        
                               return new CompositeConfiguration(configs); 
        
                           } else if (configs.size() == 1) { 
        
                               return configs.get(0); 
        
                           } 
        
                       } 
        
                       return getConfiguration(loggerContext, configLocationStr); 
        
                   } 
        
                   final String log4j1ConfigStr = this.substitutor.replace( 
        
                           PropertiesUtil.getProperties().getStringProperty(LOG4J1_CONFIGURATION_FILE_PROPERTY)); 
        
                   if (log4j1ConfigStr != null) { 
        
                       System.setProperty(LOG4J1_EXPERIMENTAL, "true"); 
        
                       return getConfiguration(LOG4J1_VERSION, loggerContext, log4j1ConfigStr); 
        
                   } 
        
                   for (final ConfigurationFactory factory : getFactories()) { 
        
                       final String[] types = factory.getSupportedTypes(); 
        
                       if (types != null) { 
        
                           for (final String type : types) { 
        
                               if (type.equals(ALL_TYPES)) { 
        
                                   final Configuration config = 
        
                                           factory.getConfiguration(loggerContext, name, configLocation); 
        
                                   if (config != null) { 
        
                                       return config; 
        
                                   } 
        
                               } 
        
                           } 
        
                       } 
        
                   } 
        
               } else { 
        
                   final String[] sources = parseConfigLocations(configLocation); 
        
                   if (sources.length > 1) { 
        
                       final List<AbstractConfiguration> configs = new ArrayList<>(); 
        
                       for (final String sourceLocation : sources) { 
        
                           final Configuration config = getConfiguration(loggerContext, sourceLocation.trim()); 
        
                           if (config instanceof AbstractConfiguration) { 
        
                               configs.add((AbstractConfiguration) config); 
        
                           } else { 
        
                               LOGGER.error("Failed to created configuration at {}", sourceLocation); 
        
                               return null; 
        
                           } 
        
                       } 
        
                       return new CompositeConfiguration(configs); 
        
                   } 
        
                   // configLocation != null 
        
                   final String configLocationStr = configLocation.toString(); 
        
                   for (final ConfigurationFactory factory : getFactories()) { 
        
                       final String[] types = factory.getSupportedTypes(); 
        
                       if (types != null) { 
        
                           for (final String type : types) { 
        
                               if (type.equals(ALL_TYPES) || configLocationStr.endsWith(type)) { 
        
                                   final Configuration config = 
        
                                           factory.getConfiguration(loggerContext, name, configLocation); 
        
                                   if (config != null) { 
        
                                       return config; 
        
                                   } 
        
                               } 
        
                           } 
        
                       } 
        
                   } 
        
               } 
        
               Configuration config = getConfiguration(loggerContext, true, name); 
        
               if (config == null) { 
        
                   config = getConfiguration(loggerContext, true, null); 
        
                   if (config == null) { 
        
                       config = getConfiguration(loggerContext, false, name); 
        
                       if (config == null) { 
        
                           config = getConfiguration(loggerContext, false, null); 
        
                       } 
        
                   } 
        
               } 
        
               if (config != null) { 
        
                   return config; 
        
               } 
        
               LOGGER.warn( 
        
                       "No Log4j 2 configuration file found. " 
        
                               + "Using default configuration (logging only errors to the console), " 
        
                               + "or user programmatically provided configurations. " 
        
                               + "Set system property 'log4j2.debug' " 
        
                               + "to show Log4j 2 internal initialization logging. " 
        
                               + "See https://logging.apache.org/log4j/2.x/manual/configuration.html for instructions on how to configure Log4j 2"); 
        
               return new DefaultConfiguration(); 
        
           }

ppkarwasz · 2025-10-12T22:48:04Z

log4j-core/src/main/java/org/apache/logging/log4j/core/config/ConfigurationFactory.java


+    /**
+     * {@return a {@link Configuration} created using provided configuration location {@link URI}s}
+     * If the provided list of {@code URI}s is null or empty, {@code getConfiguration(loggerContext, name, (URI) null)} will be returned.


Should we explain more explicitly the behavior of an empty list?

Suggested change

* If the provided list of {@code URI}s is null or empty, {@code getConfiguration(loggerContext, name, (URI) null)} will be returned.

* <p>If the provided list of {@code URI}s is empty, the configuration factory

* attempts to load an implementation-dependent set of default locations.

* If no configuration can be found, a {@link ConfigurationException} is thrown.</p>

ppkarwasz · 2025-10-12T22:50:04Z

log4j-core/src/main/java/org/apache/logging/log4j/core/config/ConfigurationFactory.java

+     *
+     * @param loggerContext a logger context, may be null
+     * @param name a configuration name, may be null
+     * @param configLocations configuration location {@code URI}s, may be null or empty


Nit: I’d prefer not to allow null for a new API and instead require callers to pass an empty list.

yybmion · 2025-10-13T07:44:59Z

Hi @vy and @ppkarwasz,

Thanks for the feedback! Before I finalize this PR, I'd like to clarify the scope of follow-up work.

Based on the discussion, I see two distinct improvement areas:

1. Factory refactoring (removing duplicate code)

I realize my comments go a bit beyond the immediate scope of this PR, but the section of code below has become a real maintenance headache. It would be great if we could take the opportunity to clean it up once and for all:

logging-log4j2/log4j-core/src/main/java/org/apache/logging/log4j/core/config/ConfigurationFactory.java

Lines 373 to 478 in 8a3fb53

public Configuration getConfiguration(

final LoggerContext loggerContext, final String name, final URI configLocation) {

if (configLocation == null) {

final String configLocationStr = this.substitutor.replace(

PropertiesUtil.getProperties().getStringProperty(CONFIGURATION_FILE_PROPERTY));

if (configLocationStr != null) {

final String[] sources = parseConfigLocations(configLocationStr);

if (sources.length > 1) {

final List<AbstractConfiguration> configs = new ArrayList<>();

for (final String sourceLocation : sources) {

final Configuration config = getConfiguration(loggerContext, sourceLocation.trim());

if (config != null) {

if (config instanceof AbstractConfiguration) {

configs.add((AbstractConfiguration) config);

} else {

LOGGER.error("Failed to created configuration at {}", sourceLocation);

return null;

}

} else {

LOGGER.warn("Unable to create configuration for {}, ignoring", sourceLocation);

}

}

if (configs.size() > 1) {

return new CompositeConfiguration(configs);

} else if (configs.size() == 1) {

return configs.get(0);

}

}

return getConfiguration(loggerContext, configLocationStr);

}

final String log4j1ConfigStr = this.substitutor.replace(

PropertiesUtil.getProperties().getStringProperty(LOG4J1_CONFIGURATION_FILE_PROPERTY));

if (log4j1ConfigStr != null) {

System.setProperty(LOG4J1_EXPERIMENTAL, "true");

return getConfiguration(LOG4J1_VERSION, loggerContext, log4j1ConfigStr);

}

for (final ConfigurationFactory factory : getFactories()) {

final String[] types = factory.getSupportedTypes();

if (types != null) {

for (final String type : types) {

if (type.equals(ALL_TYPES)) {

final Configuration config =

factory.getConfiguration(loggerContext, name, configLocation);

if (config != null) {

return config;

}

}

}

}

}

} else {

final String[] sources = parseConfigLocations(configLocation);

if (sources.length > 1) {

final List<AbstractConfiguration> configs = new ArrayList<>();

for (final String sourceLocation : sources) {

final Configuration config = getConfiguration(loggerContext, sourceLocation.trim());

if (config instanceof AbstractConfiguration) {

configs.add((AbstractConfiguration) config);

} else {

LOGGER.error("Failed to created configuration at {}", sourceLocation);

return null;

}

}

return new CompositeConfiguration(configs);

}

// configLocation != null

final String configLocationStr = configLocation.toString();

for (final ConfigurationFactory factory : getFactories()) {

final String[] types = factory.getSupportedTypes();

if (types != null) {

for (final String type : types) {

if (type.equals(ALL_TYPES) || configLocationStr.endsWith(type)) {

final Configuration config =

factory.getConfiguration(loggerContext, name, configLocation);

if (config != null) {

return config;

}

}

}

}

}

}

Configuration config = getConfiguration(loggerContext, true, name);

if (config == null) {

config = getConfiguration(loggerContext, true, null);

if (config == null) {

config = getConfiguration(loggerContext, false, name);

if (config == null) {

config = getConfiguration(loggerContext, false, null);

}

}

}

if (config != null) {

return config;

}

LOGGER.warn(

"No Log4j 2 configuration file found. "

+ "Using default configuration (logging only errors to the console), "

+ "or user programmatically provided configurations. "

+ "Set system property 'log4j2.debug' "

+ "to show Log4j 2 internal initialization logging. "

+ "See https://logging.apache.org/log4j/2.x/manual/configuration.html for instructions on how to configure Log4j 2");

return new DefaultConfiguration();

}

Delegate composite configuration logic in Factory.getConfiguration(ctx, name, URI) to the new getConfiguration(ctx, name, List<URI>) method.

2. Exception-throwing consistency

@yybmion, would you be interested in implementing changes necessary to make other ConfigurationFactory::getConfiguration methods throw on failure too?

Align all getConfiguration methods to throw exceptions instead of returning null

I'm currently working on two changes. Should I handle them in separate PRs?

github-project-automation bot added this to Log4j bug tracker Sep 8, 2025

github-project-automation bot moved this to To triage in Log4j bug tracker Sep 8, 2025

yybmion mentioned this pull request Sep 8, 2025

Add API to list supported configuration file extensions #3839

Open

8 tasks

vy requested changes Sep 26, 2025

View reviewed changes

log4j-core/src/main/java/org/apache/logging/log4j/core/config/ConfigurationFactory.java Outdated Show resolved Hide resolved

log4j-core/src/main/java/org/apache/logging/log4j/core/config/ConfigurationFactory.java Outdated Show resolved Hide resolved

yybmion force-pushed the add_getConfiguration_for_multiple_URIs branch from 9377356 to 22ba22c Compare September 26, 2025 09:28

vy requested changes Oct 3, 2025

View reviewed changes

yybmion force-pushed the add_getConfiguration_for_multiple_URIs branch from aeda617 to 40b26ea Compare October 3, 2025 14:12

vy approved these changes Oct 3, 2025

View reviewed changes

vy requested changes Oct 3, 2025

View reviewed changes

log4j-core/src/main/java/org/apache/logging/log4j/core/config/json/package-info.java Show resolved Hide resolved

yybmion force-pushed the add_getConfiguration_for_multiple_URIs branch from 6af187e to e91c25b Compare October 3, 2025 17:41

ppkarwasz mentioned this pull request Oct 7, 2025

Simplify Log4J2LoggingSystem spring-projects/spring-boot#47424

Open

Add getConfiguration method for multiple URIs

93819f2

yybmion force-pushed the add_getConfiguration_for_multiple_URIs branch from e91c25b to 93819f2 Compare October 10, 2025 08:41

ppkarwasz requested changes Oct 10, 2025

View reviewed changes

Apply review feedback

a738f0d

ppkarwasz reviewed Oct 12, 2025

View reviewed changes

-     * If the provided list of {@code URI}s is null or empty, {@code getConfiguration(loggerContext, name, (URI) null)} will be returned.
+     * <p>If the provided list of {@code URI}s is empty, the configuration factory
+     * attempts to load an implementation-dependent set of default locations.
+     * If no configuration can be found, a {@link ConfigurationException} is thrown.</p>

Uh oh!

Add getConfiguration method for multiple URIs #3921

Are you sure you want to change the base?

Add getConfiguration method for multiple URIs #3921

Uh oh!

Conversation

yybmion commented Sep 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motivation

✅ Required checks

🧪 Tests (select one)

📝 Changelog (select one)

Uh oh!

Uh oh!

Uh oh!

yybmion commented Sep 26, 2025

Uh oh!

vy commented Sep 26, 2025

Uh oh!

yybmion commented Sep 26, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yybmion commented Oct 3, 2025

Uh oh!

vy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Generated by gradle/develocity-actions

Uh oh!

yybmion commented Oct 3, 2025

Uh oh!

vy commented Oct 10, 2025

Uh oh!

yybmion commented Oct 10, 2025

Uh oh!

ppkarwasz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ppkarwasz commented Oct 10, 2025

Uh oh!

ppkarwasz Oct 12, 2025

Choose a reason for hiding this comment

Uh oh!

ppkarwasz Oct 12, 2025

Choose a reason for hiding this comment

Uh oh!

yybmion commented Oct 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

yybmion commented Sep 8, 2025 •

edited

Loading

github-actions bot commented Oct 3, 2025 •

edited

Loading