LayeredConfigurator will go through a properties files with references to DOM or Property configurator references (files or URLs), and will call the appropriate configurator in the order they are defined.
This doesn't mean much in theory, so let's explain why this package exists, and give an example.
Log4J lacks a way to spread configuration over several files. You have one configuration file, either log4j.properties or log4j.xml, and that's it.
In projects where you have several environments to keep track of, you may want to have some loggers set to DEBUG in the development environment, but set to WARN on the production environment. However, you usually want to keep all the appenders and logging infrastructure the same.
Because Log4J defines appenders and loggers in the same file, you either have to define several almost identical files with the appropriate changes for the environment, or you have to have an Ant script that goes through and replaces tokens for the appropriate environment.
The file syntax for the configurators is simple. Here's an example log4j-config.properties file:
# The complicated appenders are rendered in XML.
base-appenders.xml
# The logging levels can be defined in properties, and can use system properties
# as parameters. (in this case we assume -Dmy.environment=dev is defined)
${my.environment}-loggers.properties
The class is called LayeredConfigurator because it's meant to work in layers. The configurators are not reset, so all the settings from the previous configurator will still apply unless you override them.
When you define -Dmy.environment=dev, then your development settings will be loaded. When you define -Dmy.environment=prod, then your production settings will be loaded. Either way, your binary distribution is exactly the same, with only the environment specific properties
To enable this class, you must start the JVM with the following system properties:
-Dlog4j.configuratorClass=com.tersesystems.log4j.LayeredConfigurator -Dlog4j.configuration=log4j-config.properties
And that's it. Pretty simple solution for something that's bugged me for at least three years now.