LOG4J2-952 - Document ConfigurationBuilder and PropertiesConfiguration
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/b288e2c2 Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/b288e2c2 Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/b288e2c2 Branch: refs/heads/master Commit: b288e2c28ea0ff601afd11a3cb23e5bdeb146154 Parents: f2daf72 Author: Ralph Goers <[email protected]> Authored: Mon Sep 7 17:29:24 2015 -0700 Committer: Ralph Goers <[email protected]> Committed: Mon Sep 7 17:29:24 2015 -0700 ---------------------------------------------------------------------- .../logging/log4j/util/PropertiesUtil.java | 33 +++++++ .../builder/api/AppenderComponentBuilder.java | 1 + .../api/AppenderRefComponentBuilder.java | 1 + .../core/config/builder/api/Component.java | 1 + .../config/builder/api/ComponentBuilder.java | 3 +- .../api/CompositeFilterComponentBuilder.java | 1 + .../builder/api/ConfigurationBuilder.java | 7 ++ .../api/ConfigurationBuilderFactory.java | 3 +- .../api/CustomLevelComponentBuilder.java | 3 +- .../builder/api/FilterComponentBuilder.java | 3 +- .../builder/api/LayoutComponentBuilder.java | 3 +- .../builder/api/LoggerComponentBuilder.java | 1 + .../builder/api/RootLoggerComponentBuilder.java | 1 + .../config/builder/impl/BuiltConfiguration.java | 26 ++++++ .../impl/DefaultConfigurationBuilder.java | 12 +++ .../properties/PropertiesConfiguration.java | 1 + .../PropertiesConfigurationFactory.java | 8 +- .../logging/log4j/core/util/PropertiesUtil.java | 42 --------- .../log4j/core/util/PropertiesUtilTest.java | 17 ++++ src/site/site.xml | 2 + src/site/xdoc/manual/configuration.xml.vm | 77 ++++++++++++++++- src/site/xdoc/manual/customconfig.xml | 90 +++++++++++++++++++- 22 files changed, 284 insertions(+), 52 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertiesUtil.java ---------------------------------------------------------------------- diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertiesUtil.java b/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertiesUtil.java index 04e94e1..ab283b1 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertiesUtil.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/util/PropertiesUtil.java @@ -19,6 +19,8 @@ package org.apache.logging.log4j.util; import java.io.IOException; import java.io.InputStream; import java.net.URL; +import java.util.ArrayList; +import java.util.List; import java.util.Properties; import org.apache.logging.log4j.Logger; @@ -237,4 +239,35 @@ public final class PropertiesUtil { return new Properties(); } } + + /** + * Extracts properties that start with or are equals to the specific prefix and returns them in a + * new Properties object with the prefix removed. + * @param properties The Properties to evaluate. + * @param prefix The prefix to extract. + * @return The subset of properties. + */ + public static Properties extractSubset(Properties properties, String prefix) { + Properties subset = new Properties(); + + if (prefix == null || prefix.length() == 0) { + return subset; + } + + String prefixToMatch = prefix.charAt(prefix.length() - 1) != '.' ? prefix + '.' : prefix; + + List<String> keys = new ArrayList<>(); + + for (String key : properties.stringPropertyNames()) { + if (key.startsWith(prefixToMatch)) { + subset.setProperty(key.substring(prefixToMatch.length()), properties.getProperty(key)); + keys.add(key); + } + } + for (String key : keys) { + properties.remove(key); + } + + return subset; + } } http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/AppenderComponentBuilder.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/AppenderComponentBuilder.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/AppenderComponentBuilder.java index bf23937..4d8f6bd 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/AppenderComponentBuilder.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/AppenderComponentBuilder.java @@ -18,6 +18,7 @@ package org.apache.logging.log4j.core.config.builder.api; /** * Builder for constructing Appender Components. + * @since 2.4 */ public interface AppenderComponentBuilder extends ComponentBuilder<AppenderComponentBuilder> { http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/AppenderRefComponentBuilder.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/AppenderRefComponentBuilder.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/AppenderRefComponentBuilder.java index e874b73..a98de90 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/AppenderRefComponentBuilder.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/AppenderRefComponentBuilder.java @@ -18,6 +18,7 @@ package org.apache.logging.log4j.core.config.builder.api; /** * Assembler for constructing AppenderRef Components. + * @since 2.4 */ public interface AppenderRefComponentBuilder extends ComponentBuilder<AppenderRefComponentBuilder> { http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/Component.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/Component.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/Component.java index 55d29b5..bd84e1f 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/Component.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/Component.java @@ -24,6 +24,7 @@ import java.util.Map; /** * Container for building Configurations. This class is not normally directly manipulated by users * of the Assembler API. + * @Since 2.4 */ public class Component { http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/ComponentBuilder.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/ComponentBuilder.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/ComponentBuilder.java index 60e42b2..873c52f 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/ComponentBuilder.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/ComponentBuilder.java @@ -22,7 +22,8 @@ import org.apache.logging.log4j.core.util.Builder; /** * Builds arbitrary components and is the base type for the provided components. - * @param <T> The ComponentBuilder's own type for fluent APIs + * @param <T> The ComponentBuilder's own type for fluent APIs. + * @since 2.4 */ public interface ComponentBuilder<T extends ComponentBuilder<T>> extends Builder<Component> { http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/CompositeFilterComponentBuilder.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/CompositeFilterComponentBuilder.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/CompositeFilterComponentBuilder.java index 73116cb..b0877d3 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/CompositeFilterComponentBuilder.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/CompositeFilterComponentBuilder.java @@ -25,6 +25,7 @@ public interface CompositeFilterComponentBuilder extends ComponentBuilder<Compos * Add a FilterComponent. * @param assembler The FilterComponentBuilder with all of its attributes and sub-components set. * @return The CompositeFilterComponentBuilder. + * @since 2.4 */ CompositeFilterComponentBuilder add(FilterComponentBuilder assembler); } http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.java index c2ec498..2bb84e2 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.java @@ -25,6 +25,7 @@ import org.apache.logging.log4j.core.util.Builder; /** * Interface for building logging configurations. * @param <T> The Configuration type created by this builder. + * @since 2.4 */ public interface ConfigurationBuilder<T extends Configuration> extends Builder<T> { @@ -199,6 +200,12 @@ public interface ConfigurationBuilder<T extends Configuration> extends Builder<T */ RootLoggerComponentBuilder newRootLogger(String level); + /** + * Set the Advertiser Plugin name. + * @param advertiser The Advertiser Plugin name. + * @return this builder instance. + */ + ConfigurationBuilder<T> setAdvertiser(String advertiser); /** * Sets the name of the configuration. http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilderFactory.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilderFactory.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilderFactory.java index 4418d38..c58b229 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilderFactory.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilderFactory.java @@ -21,7 +21,8 @@ import org.apache.logging.log4j.core.config.builder.impl.BuiltConfiguration; import org.apache.logging.log4j.core.config.builder.impl.DefaultConfigurationBuilder; /** - * + * Provides methods to create ConfigurationBuilders. + * @since 2.4 */ public class ConfigurationBuilderFactory { http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/CustomLevelComponentBuilder.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/CustomLevelComponentBuilder.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/CustomLevelComponentBuilder.java index 38230e2..de9a073 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/CustomLevelComponentBuilder.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/CustomLevelComponentBuilder.java @@ -17,7 +17,8 @@ package org.apache.logging.log4j.core.config.builder.api; /** - * Assembler for constructing CustomLevel Components + * Assembler for constructing CustomLevel Components. + * @since 2.4 */ public interface CustomLevelComponentBuilder extends ComponentBuilder<CustomLevelComponentBuilder> { http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/FilterComponentBuilder.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/FilterComponentBuilder.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/FilterComponentBuilder.java index 232fd5e..f65bfdd 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/FilterComponentBuilder.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/FilterComponentBuilder.java @@ -17,7 +17,8 @@ package org.apache.logging.log4j.core.config.builder.api; /** - * Assembler for constructing Filter Components + * Assembler for constructing Filter Components. + * @since 2.4 */ public interface FilterComponentBuilder extends ComponentBuilder<FilterComponentBuilder> { http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/LayoutComponentBuilder.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/LayoutComponentBuilder.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/LayoutComponentBuilder.java index ef893ac..e2eb7b5 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/LayoutComponentBuilder.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/LayoutComponentBuilder.java @@ -17,7 +17,8 @@ package org.apache.logging.log4j.core.config.builder.api; /** - * Assembler for constructing Layout Components + * Assembler for constructing Layout Components. + * @since 2.4 */ public interface LayoutComponentBuilder extends ComponentBuilder<LayoutComponentBuilder> { http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/LoggerComponentBuilder.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/LoggerComponentBuilder.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/LoggerComponentBuilder.java index 4dcbf00..fcca42b 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/LoggerComponentBuilder.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/LoggerComponentBuilder.java @@ -18,6 +18,7 @@ package org.apache.logging.log4j.core.config.builder.api; /** * Assembler for constructing Logger Components. + * @since 2.4 */ public interface LoggerComponentBuilder extends ComponentBuilder<LoggerComponentBuilder> { http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/RootLoggerComponentBuilder.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/RootLoggerComponentBuilder.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/RootLoggerComponentBuilder.java index 4c7a681..324eb99 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/RootLoggerComponentBuilder.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/api/RootLoggerComponentBuilder.java @@ -18,6 +18,7 @@ package org.apache.logging.log4j.core.config.builder.api; /** * Assembler for constructing the root Logger Components. + * @since 2.4 */ public interface RootLoggerComponentBuilder extends ComponentBuilder<RootLoggerComponentBuilder> { http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/impl/BuiltConfiguration.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/impl/BuiltConfiguration.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/impl/BuiltConfiguration.java index 0b838d2..06135e8 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/impl/BuiltConfiguration.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/impl/BuiltConfiguration.java @@ -29,6 +29,8 @@ import org.apache.logging.log4j.core.config.status.StatusConfiguration; import org.apache.logging.log4j.core.util.Patterns; import java.io.File; +import java.io.IOException; +import java.io.InputStream; import java.util.Arrays; import java.util.List; @@ -46,6 +48,7 @@ public class BuiltConfiguration extends AbstractConfiguration { private Component filtersComponent; private Component propertiesComponent; private Component customLevelsComponent; + private String contentType = "text"; public BuiltConfiguration(final ConfigurationSource source, final Component rootComponent) { super(source); @@ -98,6 +101,29 @@ public class BuiltConfiguration extends AbstractConfiguration { root = null; } + public String getContentType() { + return this.contentType; + } + + public void setContentType(String contentType) { + this.contentType = contentType; + } + + public void createAdvertiser(final String advertiserString, final ConfigurationSource configSource) { + byte[] buffer = null; + try { + if (configSource != null) { + InputStream is = configSource.getInputStream(); + if (is != null) { + buffer = toByteArray(is); + } + } + } catch (IOException ioe) { + LOGGER.warn("Unable to read configuration source " + configSource.toString()); + } + super.createAdvertiser(advertiserString, configSource, buffer, contentType); + } + public StatusConfiguration getStatusConfiguration() { return statusConfig; } http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/impl/DefaultConfigurationBuilder.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/impl/DefaultConfigurationBuilder.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/impl/DefaultConfigurationBuilder.java index e795bfc..386226a 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/impl/DefaultConfigurationBuilder.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/builder/impl/DefaultConfigurationBuilder.java @@ -32,6 +32,7 @@ import org.apache.logging.log4j.core.config.builder.api.LayoutComponentBuilder; import org.apache.logging.log4j.core.config.builder.api.LoggerComponentBuilder; import org.apache.logging.log4j.core.config.builder.api.RootLoggerComponentBuilder; +import java.io.InputStream; import java.lang.reflect.Constructor; import java.util.List; @@ -54,6 +55,8 @@ public class DefaultConfigurationBuilder<T extends BuiltConfiguration> implement private String verbosity = null; private String packages = null; private String shutdownFlag = null; + private String advertiser = null; + private byte[] buffer = null; private String name = null; @@ -146,6 +149,9 @@ public class DefaultConfigurationBuilder<T extends BuiltConfiguration> implement if (shutdownFlag != null) { configuration.setShutdownHook(shutdownFlag); } + if (advertiser != null) { + configuration.createAdvertiser(advertiser, source); + } } catch (final Exception ex) { throw new IllegalArgumentException("Invalid Configuration class specified", ex); } @@ -236,6 +242,12 @@ public class DefaultConfigurationBuilder<T extends BuiltConfiguration> implement return new DefaultRootLoggerComponentBuilder(this, level); } + @Override + public ConfigurationBuilder<T> setAdvertiser(final String advertiser) { + this.advertiser = advertiser; + return this; + } + /** * Set the name of the configuration. * http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/log4j-core/src/main/java/org/apache/logging/log4j/core/config/properties/PropertiesConfiguration.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/properties/PropertiesConfiguration.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/properties/PropertiesConfiguration.java index ae0e49c..19dbbf3 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/properties/PropertiesConfiguration.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/properties/PropertiesConfiguration.java @@ -26,6 +26,7 @@ import java.io.IOException; /** * Configuration created from a properties file. + * @since 2.4 */ public class PropertiesConfiguration extends BuiltConfiguration implements Reconfigurable { http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/log4j-core/src/main/java/org/apache/logging/log4j/core/config/properties/PropertiesConfigurationFactory.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/properties/PropertiesConfigurationFactory.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/properties/PropertiesConfigurationFactory.java index 092afd1..1dfb19c 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/properties/PropertiesConfigurationFactory.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/properties/PropertiesConfigurationFactory.java @@ -30,7 +30,7 @@ import org.apache.logging.log4j.core.config.builder.api.LayoutComponentBuilder; import org.apache.logging.log4j.core.config.builder.api.LoggerComponentBuilder; import org.apache.logging.log4j.core.config.builder.api.RootLoggerComponentBuilder; import org.apache.logging.log4j.core.config.plugins.Plugin; -import org.apache.logging.log4j.core.util.PropertiesUtil; +import org.apache.logging.log4j.util.PropertiesUtil; import org.apache.logging.log4j.util.Strings; import java.io.IOException; @@ -39,10 +39,12 @@ import java.util.Properties; /** * Creates a PropertiesConfiguration from a properties file. + * @since 2.4 */ @Plugin(name = "PropertiesConfigurationFactory", category = ConfigurationFactory.CATEGORY) @Order(8) public class PropertiesConfigurationFactory extends ConfigurationFactory { + private static final String ADVERTISER_KEY = "advertiser"; private static final String STATUS_KEY = "status"; private static final String SHUTDOWN_HOOK = "shutdownHook"; private static final String VERBOSE = "verbose"; @@ -92,6 +94,10 @@ public class PropertiesConfigurationFactory extends ConfigurationFactory { if (value != null) { builder.setMonitorInterval(value); } + value = properties.getProperty(ADVERTISER_KEY); + if (value != null) { + builder.setAdvertiser(value); + } Properties props = PropertiesUtil.extractSubset(properties, "property"); for (String key : props.stringPropertyNames()) { builder.addProperty(key, props.getProperty(key)); http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/log4j-core/src/main/java/org/apache/logging/log4j/core/util/PropertiesUtil.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/util/PropertiesUtil.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/util/PropertiesUtil.java deleted file mode 100644 index c43ce93..0000000 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/util/PropertiesUtil.java +++ /dev/null @@ -1,42 +0,0 @@ -package org.apache.logging.log4j.core.util; - -import java.util.ArrayList; -import java.util.List; -import java.util.Properties; - -/** - * - */ -public class PropertiesUtil { - - /** - * Extracts properties that start with or are equals to the specific prefix and returns them in a - * new Properties object with the prefix removed. - * @param properties The Properties to evaluate. - * @param prefix The prefix to extract. - * @return The subset of properties. - */ - public static Properties extractSubset(Properties properties, String prefix) { - Properties subset = new Properties(); - - if (prefix == null || prefix.length() == 0) { - return subset; - } - - String prefixToMatch = prefix.charAt(prefix.length() - 1) != '.' ? prefix + '.' : prefix; - - List<String> keys = new ArrayList<>(); - - for (String key : properties.stringPropertyNames()) { - if (key.startsWith(prefixToMatch)) { - subset.setProperty(key.substring(prefixToMatch.length()), properties.getProperty(key)); - keys.add(key); - } - } - for (String key : keys) { - properties.remove(key); - } - - return subset; - } -} http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/log4j-core/src/test/java/org/apache/logging/log4j/core/util/PropertiesUtilTest.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/test/java/org/apache/logging/log4j/core/util/PropertiesUtilTest.java b/log4j-core/src/test/java/org/apache/logging/log4j/core/util/PropertiesUtilTest.java index 0fc6f20..5df1a68 100644 --- a/log4j-core/src/test/java/org/apache/logging/log4j/core/util/PropertiesUtilTest.java +++ b/log4j-core/src/test/java/org/apache/logging/log4j/core/util/PropertiesUtilTest.java @@ -1,5 +1,22 @@ +/* + * 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. + */ package org.apache.logging.log4j.core.util; +import org.apache.logging.log4j.util.PropertiesUtil; import org.junit.Test; import java.io.FileInputStream; http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/src/site/site.xml ---------------------------------------------------------------------- diff --git a/src/site/site.xml b/src/site/site.xml index 3bbf745..23095d4 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -67,6 +67,7 @@ <item name="Configuration Syntax" href="/manual/configuration.html#ConfigurationSyntax" /> <item name="XML Syntax" href="/manual/configuration.html#XML"/> <item name="JSON Syntax" href="/manual/configuration.html#JSON"/> + <item name="Properties Syntax" href="/manual/configuration.html#Properties"/> <item name="Configuring Loggers" href="/manual/configuration.html#Loggers"/> <item name="Configuring Appenders" href="/manual/configuration.html#Appenders"/> <item name="Configuring Filters" href="/manual/configuration.html#Filters"/> @@ -184,6 +185,7 @@ <item name="Extending Log4j Configuration" href="/manual/customconfig.html" collapse="true"> <item name="ConfigurationFactory" href="/manual/customconfig.html#ConfigurationFactory"/> + <item name="ConfigurationBuilder" href="/manual/customconfig.html#ConfigurationBuilder"/> <item name="Manual" href="/manual/customconfig.html#AddingToCurrent"/> </item> http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/src/site/xdoc/manual/configuration.xml.vm ---------------------------------------------------------------------- diff --git a/src/site/xdoc/manual/configuration.xml.vm b/src/site/xdoc/manual/configuration.xml.vm index a4c0e20..054dcd3 100644 --- a/src/site/xdoc/manual/configuration.xml.vm +++ b/src/site/xdoc/manual/configuration.xml.vm @@ -359,8 +359,6 @@ public class Bar { as the action being performed for a specific user, route output to Flume or a log reporting system, etc. Being able to do this requires understanding the syntax of the configuration files. </p> - <a name="XML"/> - <h4>Configuration with XML</h4> <p> The configuration element in the XML file accepts several attributes: </p> @@ -807,6 +805,81 @@ public class Bar { </Configuration> ]]></pre> + <a name="Properties"/> + <h4>Configuration with Properties</h4> + <p> + As of version 2.4, Log4j now supports configuration via properties files. Note that the property + syntax is NOT the same as the syntax used in Log4j 1. Like the XML and JSON configurations, properties + configurations define the configuration in terms of plugins and attributes to the plugins. + </p> + <p> + The properties configuration requires that you list the identifiers of the appenders, filters and loggers, + in a comma separated list in properties with those names. Each of those components will then be expected + to be defined in sets of properties that begin with <i>component.identifier</i>. The identifier does not + have to match the name of the component being defined but must uniquely identify all the attributes and + subcomponents that are part of the component. Each individual component MUST have a "type" attribute + specified that identifies the component's Plugin type. + </p> + <p> + Unlike the base components, when creating subcomponents you cannot specify an element containing a list of + identifiers. Instead, you must define the wrapper element with its type as is shown in the policies + definition in the rolling file appender below. You then define each of the subcomponents below that + wrapper element, as the TimeBasedTriggeringPolicy and SizeBasedTriggeringPolicy are defined below. + </p> + <p> + Properties configuration files support the advertiser, monitorInterval, name, packages, shutdownHook, + status, and verbose attrbutes. See <a href="#ConfigurationSyntax">Configuration Syntax</a> for the + definitions of these attributes. + </p> + <pre class="prettyprint linenums"> +status = error +name = PropertiesConfig + +property.filename = target/rolling/rollingtest.log + +filters = threshold + +filter.threshold.type = ThresholdFilter +filter.threshold.level = debug + +appenders = console, rolling, list + +appender.console.type = Console +appender.console.name = STDOUT +appender.console.layout.type = PatternLayout +appender.console.layout.pattern = %m%n + +appender.rolling.type = RollingFile +appender.rolling.name = RollingFile +appender.rolling.fileName = ${filename} +appender.rolling.filePattern = target/rolling2/test1-%d{MM-dd-yy-HH-mm-ss}-%i.log.gz +appender.rolling.layout.type = PatternLayout +appender.rolling.layout.pattern = %d %p %C{1.} [%t] %m%n +appender.rolling.policies.type = Policies +appender.rolling.policies.time.type = TimeBasedTriggeringPolicy +appender.rolling.policies.time.interval = 2 +appender.rolling.policies.time.modulate = true +appender.rolling.policies.size.type = SizeBasedTriggeringPolicy +appender.rolling.policies.size.size=100MB + +appender.list.type = List +appender.list.name = List +appender.list.filters = threshold +appender.list.filter.threshold.type = ThresholdFilter +appender.list.filter.threshold.level = error + +loggers = rolling + +logger.rolling.name = org.apache.logging.log4j.core.appender.rolling +logger.rolling.level = debug +logger.rolling.additivity = false +logger.rolling.appenderRefs = rolling +logger.rolling.appenderRef.rolling.ref = RollingFile + +rootLogger.level = info +rootLogger.appenderRefs = stdout +rootLogger.appenderRef.stdout.ref = STDOUT + </pre> </subsection> <a name="PropertySubstitution"/> <subsection name="Property Substitution"> http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b288e2c2/src/site/xdoc/manual/customconfig.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/manual/customconfig.xml b/src/site/xdoc/manual/customconfig.xml index 52da59a..76fb13d 100644 --- a/src/site/xdoc/manual/customconfig.xml +++ b/src/site/xdoc/manual/customconfig.xml @@ -35,7 +35,7 @@ The easiest way to create a custom Configuration is to extend one of the standard Configuration classes (XMLConfiguration, JSONConfiguration) and then create a new ConfigurationFactory for the extended class. After the standard configuration completes the custom configuration can be added to it. - </p> + </p>> <p> The example below shows how to extend XMLConfiguration to manually add an Appender and a LoggerConfig to the configuration. @@ -89,9 +89,95 @@ public class MyXMLConfiguration extends XMLConfiguration { addLogger("org.apache.logging.log4j", loggerConfig); } }</pre> + <p> + Another way to create a ConfigurationFactory is to use the <a href="#ConfigurationBuilder">ConfigurationBuilder</a>. + This will cause the Configuration to automatically be hooked into Log4j when the LoggerContext is created. + In the example below, because it specifies a supported type of "*" it will override any configuration files provided. + </p> + <pre class="prettyprint linenum"><![CDATA[ +@Plugin(name = "CustomConfigurationFactory", category = ConfigurationFactory.CATEGORY) +@Order(50) +public class CustomConfigurationFactory extends ConfigurationFactory { + + static Configuration addTestFixtures(final String name, ConfigurationBuilder<BuiltConfiguration> builder) { + builder.setConfigurationName(name); + builder.setStatusLevel(Level.ERROR); + builder.add(builder.newFilter("ThresholdFilter", Filter.Result.ACCEPT, Filter.Result.NEUTRAL). + addAttribute("level", Level.DEBUG)); + AppenderComponentBuilder appenderBuilder = builder.newAppender("Stdout", "CONSOLE"). + addAttribute("target", ConsoleAppender.Target.SYSTEM_OUT); + appenderBuilder.add(builder.newLayout("PatternLayout"). + addAttribute("pattern", "%d [%t] %-5level: %msg%n%throwable")); + appenderBuilder.add(builder.newFilter("MarkerFilter", Filter.Result.DENY, + Filter.Result.NEUTRAL).addAttribute("marker", "FLOW")); + builder.add(appenderBuilder); + builder.add(builder.newLogger("org.apache.logging.log4j", Level.DEBUG). + add(builder.newAppenderRef("Stdout")). + addAttribute("additivity", false)); + builder.add(builder.newRootLogger(Level.ERROR).add(builder.newAppenderRef("Stdout"))); + return builder.build(); + } + + @Override + public Configuration getConfiguration(ConfigurationSource source) { + return getConfiguration(source.toString(), null); + } + + @Override + public Configuration getConfiguration(final String name, final URI configLocation) { + ConfigurationBuilder<BuiltConfiguration> builder = newConfigurationBuilder(); + return addTestFixtures(name, builder); + } + + @Override + protected String[] getSupportedTypes() { + return new String[] {"*"}; + } +}]]></pre> </subsection> + <a name="ConfigurationBuilder"/> + <subsection name="ConfigurationBuilder"> + <p> + Starting with release 2.4, Log4j provides a ConfigurationBuilder and a set of component builders that + allow a Configuration to be created fairly easily. The component builders construct component definitions + that are added to the ConfigurationBuilder. Once all the definitions have been collected all the actual + configuration objects are constructed. This Configuration may then be passed to the Configurator to set + up the Log4j configuration. + </p> + <p> + The ConfigurationBuilder is aware of the base components that can be cofigured such as Loggers, Appenders, + Filter, Properties, etc. However, it does know what components can be configured on specific components + such as the RollingFileAppender vs the RoutingAppender. As an example, when creating an appender + builder.newFilter() can be called to create a Filter and then the add method can be called on the + AppenderComponentBuilder to add the Filter to the Appender. However, the configuration builder doesn't + know anything about triggering policies. For these, builder.newComponent() must be used. + </p> + <p> + Using the Configurator in this manner allows the application control over when Log4j is initialized. + However, should any logging be attempted before Configurator.initialize() is called then the + default configuration will be used for those log events. + </p> + <pre class="prettyprint linenum"><![CDATA[ +ConfigurationBuilder<BuiltConfiguration> builder = ConfigurationBuilderFactory.newConfigurationBuilder(); +builder.setStatusLevel(Level.ERROR); +builder.setConfigurationName("BuilderTest"); +builder.add(builder.newFilter("ThresholdFilter", Filter.Result.ACCEPT, Filter.Result.NEUTRAL) + .addAttribute("level", Level.DEBUG)); +AppenderComponentBuilder appenderBuilder = builder.newAppender("Stdout", "CONSOLE").addAttribute("target", + ConsoleAppender.Target.SYSTEM_OUT); +appenderBuilder.add(builder.newLayout("PatternLayout"). + addAttribute("pattern", "%d [%t] %-5level: %msg%n%throwable")); +appenderBuilder.add(builder.newFilter("MarkerFilter", Filter.Result.DENY, Filter.Result.NEUTRAL). + addAttribute("marker", "FLOW")); +builder.add(appenderBuilder); +builder.add(builder.newLogger("org.apache.logging.log4j", Level.DEBUG). + add(builder.newAppenderRef("Stdout")).addAttribute("additivity", false)); +builder.add(builder.newRootLogger(Level.ERROR).add(builder.newAppenderRef("Stdout"))); +ctx = Configurator.initialize(builder.build()); +]]></pre> + </subsection> <a name="AddingToCurrent"/> - <subsection name="Programatically Adding to the Current Configuration"> + <subsection name="Programatically Adding to the Current Configuration"> <p> Applications sometimes have the need to customize logging separate from the actual configuration. Log4j allows this although it suffers from a few limitations:
