Top Description Inners Fields Constructors Methods
org.apache.logging.log4j.util

public final Class PropertiesUtil

extends Object
Class Inheritance
Annotations
@ServiceConsumer:PropertySource
resolution:optional
cardinality:multiple
Imports
aQute.bnd.annotation.Cardinality, .Resolution, aQute.bnd.annotation.spi.ServiceConsumer, java.io.IOException, .InputStream, java.lang.invoke.MethodHandles, java.nio.charset.Charset, java.time.Duration, java.time.temporal.ChronoUnit, .TemporalUnit, java.util.ArrayList, .HashSet, .List, .Map, .Objects, .Properties, .ResourceBundle, .ServiceLoader, .Set, java.util.concurrent.ConcurrentHashMap, .ConcurrentSkipListSet
Consider this class private.

Provides utility methods for managing Properties instances as well as access to the global configuration system. Properties by default are loaded from the system properties, system environment, and a classpath resource file named log4j2.component.properties. Additional properties can be loaded by implementing a custom PropertySource service and specifying it via a ServiceLoader file called META-INF/services/org.apache.logging.log4j.util.PropertySource with a list of fully qualified class names implementing that interface.

See Also
PropertySource

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
PropertiesUtil.Environment

Provides support for looking up global configuration properties via environment variables, property files, and system properties, in three variations:

Normalized: all log4j-related prefixes removed, remaining property is camelCased with a log4j2 prefix for property files and system properties, or follows a LOG4J_FOO_BAR format for environment variables.

private static enum
PropertiesUtil.TimeUnit

Field Summary

Modifier and TypeField and Description
private static final Lazy<PropertiesUtil>
COMPONENT_PROPERTIES

private final PropertiesUtil.Environment
environment

private static final String
LOG4J_PROPERTIES_FILE_NAME

private static final String
LOG4J_SYSTEM_PROPERTIES_FILE_NAME

Constructor Summary

AccessConstructor and Description
public
PropertiesUtil(final Properties
the Properties to use by default
props)

Constructs a PropertiesUtil using a given Properties object as its source of defined properties.

public
PropertiesUtil(final String
the location of properties file to load
propertiesFileName)

Constructs a PropertiesUtil for a given properties file name on the classpath.

private
PropertiesUtil(final String propertiesFileName, final boolean useTccl)

pack-priv
PropertiesUtil(final PropertySource
a property source
source)

Constructs a PropertiesUtil for a give property source as source of additional properties.

Method Summary

Modifier and TypeMethod and Description
public void
addPropertySource(final PropertySource
the PropertySource to add.
propertySource)

Allows a PropertySource to be added after PropertiesUtil has been created.

public static Properties

Returns:

The subset of properties.
extractSubset(final Properties
The Properties to evaluate.
properties, final String
The prefix to extract.
prefix)

Extracts properties that start with or are equals to the specific prefix and returns them in a new Properties object with the prefix removed.

public boolean

Returns:

the boolean value of the property or false if undefined.
getBooleanProperty(final String
the name of the property to look up
name)

Gets the named property as a boolean value.

public boolean

Returns:

the boolean value of the property or defaultValue if undefined.
getBooleanProperty(final String
the name of the property to look up
name, final boolean
the default value to use if the property is undefined
defaultValue)

Gets the named property as a boolean value.

public boolean

Returns:

the boolean value of the property or defaultValue if undefined.
getBooleanProperty(final String
the name of the property to look up
name, final boolean
the default value to use if the property is undefined
defaultValueIfAbsent, final boolean
the default value to use if the property is defined but not assigned
defaultValueIfPresent)

Gets the named property as a boolean value.

public Boolean

Returns:

The value or null if it is not found.
getBooleanProperty(final String[]
The array of prefixes.
prefixes, final String
The key to locate.
key, final Supplier<Boolean>
The method to call to derive the default value. If the value is null, null will be returned if no property is found.
supplier)
References Deprecated Supplier is deprecated or references (maybe indirectly) at least one deprecated element.

Retrieves a property that may be prefixed by more than one string.

public Charset

Returns:

the Charset value of the property or Charset#defaultCharset() if undefined.
getCharsetProperty(final String
the name of the property to look up
name)

Gets the named property as a Charset value.

public Charset

Returns:

the Charset value of the property or defaultValue if undefined.
getCharsetProperty(final String
the name of the property to look up
name, final Charset
the default value to use if the property is undefined
defaultValue)

Gets the named property as a Charset value.

pack-priv static ResourceBundle
getCharsetsResourceBundle()

public double

Returns:

the parsed double value of the property or defaultValue if it was undefined or could not be parsed.
getDoubleProperty(final String
the name of the property to look up
name, final double
the default value to use if the property is undefined
defaultValue)

Gets the named property as a double.

public Duration

Returns:

The value of the String as a Duration or the default value, which may be null.
getDurationProperty(final String
The property name.
name, final Duration
The default value.
defaultValue)

Retrieves a Duration where the String is of the format nnn[unit] where nnn represents an integer value and unit represents a time unit.

public Duration

Returns:

The value or null if it is not found.
getDurationProperty(final String[]
The array of prefixes.
prefixes, final String
The key to locate.
key, final Supplier<Duration>
The method to call to derive the default value. If the value is null, null will be returned if no property is found.
supplier)
References Deprecated Supplier is deprecated or references (maybe indirectly) at least one deprecated element.

Retrieves a property that may be prefixed by more than one string.

public int

Returns:

the parsed integer value of the property or defaultValue if it was undefined or could not be parsed.
getIntegerProperty(final String
the name of the property to look up
name, final int
the default value to use if the property is undefined
defaultValue)

Gets the named property as an integer.

public Integer

Returns:

The value or null if it is not found.
getIntegerProperty(final String[]
The array of prefixes.
prefixes, final String
The key to locate.
key, final Supplier<Integer>
The method to call to derive the default value. If the value is null, null will be returned if no property is found.
supplier)
References Deprecated Supplier is deprecated or references (maybe indirectly) at least one deprecated element.

Retrieves a property that may be prefixed by more than one string.

public long

Returns:

the parsed long value of the property or defaultValue if it was undefined or could not be parsed.
getLongProperty(final String
the name of the property to look up
name, final long
the default value to use if the property is undefined
defaultValue)

Gets the named property as a long.

public Long

Returns:

The value or null if it is not found.
getLongProperty(final String[]
The array of prefixes.
prefixes, final String
The key to locate.
key, final Supplier<Long>
The method to call to derive the default value. If the value is null, null will be returned if no property is found.
supplier)
References Deprecated Supplier is deprecated or references (maybe indirectly) at least one deprecated element.

Retrieves a property that may be prefixed by more than one string.

public static PropertiesUtil

Returns:

the main Log4j PropertiesUtil instance.
getProperties()

Returns the PropertiesUtil used by Log4j.

public String

Returns:

The value or null if it is not found.
getStringProperty(final String[]
The array of prefixes.
prefixes, final String
The key to locate.
key, final Supplier<String>
The method to call to derive the default value. If the value is null, null will be returned if no property is found.
supplier)
References Deprecated Supplier is deprecated or references (maybe indirectly) at least one deprecated element.

Retrieves a property that may be prefixed by more than one string.

public String

Returns:

the String value of the property or null if undefined.
getStringProperty(final String
the name of the property to look up
name)

Gets the named property as a String.

public String

Returns:

the String value of the property or defaultValue if undefined.
getStringProperty(final String
the name of the property to look up
name, final String
the default value to use if the property is undefined
defaultValue)

Gets the named property as a String.

public static Properties

Returns:

The system properties.
getSystemProperties()

Return the system properties or an empty Properties object if an error occurs.

public boolean

Returns:

true if the specified property is defined, regardless of its value
hasProperty(final String
the name of the property to verify
name)

Returns true if the specified property is defined, regardless of its value (it may not have a value).

public boolean

Returns:

true if system properties tell us we are running on Windows.
isOsWindows()

Returns true if system properties tell us we are running on Windows.

pack-priv static Properties

Returns:

a new Properties object
loadClose(final InputStream
a property input stream.
in, final Object
a source object describing the source, like a resource string or a URL.
source)

Loads and closes the given property input stream.

public static Map<String, Properties>

Returns:

the partitioned properties where each key is the common prefix (minus the period) and the values are new property maps without the prefix and period in the key
partitionOnCommonPrefixes(final Properties
properties to partition
properties)

Partitions a properties map based on common key prefixes up to the first period.

public static Map<String, Properties>

Returns:

the partitioned properties where each key is the common prefix (minus the period) and the values are new property maps without the prefix and period in the key
partitionOnCommonPrefixes(final Properties
properties to partition
properties, final boolean
when true if a key exists with no '.' the key will be included.
includeBaseKey)

Partitions a properties map based on common key prefixes up to the first period.

public void
reload()

Reloads all properties.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

COMPONENT_PROPERTIESback to summary
private static final Lazy<PropertiesUtil> COMPONENT_PROPERTIES
environmentback to summary
private final PropertiesUtil.Environment environment
LOG4J_PROPERTIES_FILE_NAMEback to summary
private static final String LOG4J_PROPERTIES_FILE_NAME
LOG4J_SYSTEM_PROPERTIES_FILE_NAMEback to summary
private static final String LOG4J_SYSTEM_PROPERTIES_FILE_NAME

Constructor Detail

PropertiesUtilback to summary
public PropertiesUtil(final Properties props)

Constructs a PropertiesUtil using a given Properties object as its source of defined properties.

Parameters
props:Properties

the Properties to use by default

PropertiesUtilback to summary
public PropertiesUtil(final String propertiesFileName)

Constructs a PropertiesUtil for a given properties file name on the classpath. The properties specified in this file are used by default. If a property is not defined in this file, then the equivalent system property is used.

Parameters
propertiesFileName:String

the location of properties file to load

PropertiesUtilback to summary
private PropertiesUtil(final String propertiesFileName, final boolean useTccl)
PropertiesUtilback to summary
pack-priv PropertiesUtil(final PropertySource source)

Constructs a PropertiesUtil for a give property source as source of additional properties.

Parameters
source:PropertySource

a property source

Method Detail

addPropertySourceback to summary
public void addPropertySource(final PropertySource propertySource)

Allows a PropertySource to be added after PropertiesUtil has been created.

Parameters
propertySource:PropertySource

the PropertySource to add.

extractSubsetback to summary
public static Properties extractSubset(final Properties properties, final String prefix)

Extracts properties that start with or are equals to the specific prefix and returns them in a new Properties object with the prefix removed.

Parameters
properties:Properties

The Properties to evaluate.

prefix:String

The prefix to extract.

Returns:Properties

The subset of properties.

getBooleanPropertyback to summary
public boolean getBooleanProperty(final String name)

Gets the named property as a boolean value. If the property matches the string "true" (case-insensitive), then it is returned as the boolean value true. Any other non-null text in the property is considered false.

Parameters
name:String

the name of the property to look up

Returns:boolean

the boolean value of the property or false if undefined.

getBooleanPropertyback to summary
public boolean getBooleanProperty(final String name, final boolean defaultValue)

Gets the named property as a boolean value.

Parameters
name:String

the name of the property to look up

defaultValue:boolean

the default value to use if the property is undefined

Returns:boolean

the boolean value of the property or defaultValue if undefined.

getBooleanPropertyback to summary
public boolean getBooleanProperty(final String name, final boolean defaultValueIfAbsent, final boolean defaultValueIfPresent)

Gets the named property as a boolean value.

Parameters
name:String

the name of the property to look up

defaultValueIfAbsent:boolean

the default value to use if the property is undefined

defaultValueIfPresent:boolean

the default value to use if the property is defined but not assigned

Returns:boolean

the boolean value of the property or defaultValue if undefined.

getBooleanPropertyback to summary
public Boolean getBooleanProperty(final String[] prefixes, final String key, final Supplier<Boolean> supplier)

References Deprecated

Supplier is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

Retrieves a property that may be prefixed by more than one string.

Parameters
prefixes:String[]

The array of prefixes.

key:String

The key to locate.

supplier:Supplier<Boolean>

The method to call to derive the default value. If the value is null, null will be returned if no property is found.

Returns:Boolean

The value or null if it is not found.

Annotations
@SuppressWarnings:deprecation
Since
2.13.0
getCharsetPropertyback to summary
public Charset getCharsetProperty(final String name)

Gets the named property as a Charset value.

Parameters
name:String

the name of the property to look up

Returns:Charset

the Charset value of the property or Charset#defaultCharset() if undefined.

getCharsetPropertyback to summary
public Charset getCharsetProperty(final String name, final Charset defaultValue)

Gets the named property as a Charset value. If we cannot find the named Charset, see if it is mapped in file Log4j-charsets.properties on the class path.

Parameters
name:String

the name of the property to look up

defaultValue:Charset

the default value to use if the property is undefined

Returns:Charset

the Charset value of the property or defaultValue if undefined.

getCharsetsResourceBundleback to summary
pack-priv static ResourceBundle getCharsetsResourceBundle()
getDoublePropertyback to summary
public double getDoubleProperty(final String name, final double defaultValue)

Gets the named property as a double.

Parameters
name:String

the name of the property to look up

defaultValue:double

the default value to use if the property is undefined

Returns:double

the parsed double value of the property or defaultValue if it was undefined or could not be parsed.

getDurationPropertyback to summary
public Duration getDurationProperty(final String name, final Duration defaultValue)

Retrieves a Duration where the String is of the format nnn[unit] where nnn represents an integer value and unit represents a time unit.

Parameters
name:String

The property name.

defaultValue:Duration

The default value.

Returns:Duration

The value of the String as a Duration or the default value, which may be null.

Since
2.13.0
getDurationPropertyback to summary
public Duration getDurationProperty(final String[] prefixes, final String key, final Supplier<Duration> supplier)

References Deprecated

Supplier is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

Retrieves a property that may be prefixed by more than one string.

Parameters
prefixes:String[]

The array of prefixes.

key:String

The key to locate.

supplier:Supplier<Duration>

The method to call to derive the default value. If the value is null, null will be returned if no property is found.

Returns:Duration

The value or null if it is not found.

Annotations
@SuppressWarnings:deprecation
Since
2.13.0
getIntegerPropertyback to summary
public int getIntegerProperty(final String name, final int defaultValue)

Gets the named property as an integer.

Parameters
name:String

the name of the property to look up

defaultValue:int

the default value to use if the property is undefined

Returns:int

the parsed integer value of the property or defaultValue if it was undefined or could not be parsed.

getIntegerPropertyback to summary
public Integer getIntegerProperty(final String[] prefixes, final String key, final Supplier<Integer> supplier)

References Deprecated

Supplier is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

Retrieves a property that may be prefixed by more than one string.

Parameters
prefixes:String[]

The array of prefixes.

key:String

The key to locate.

supplier:Supplier<Integer>

The method to call to derive the default value. If the value is null, null will be returned if no property is found.

Returns:Integer

The value or null if it is not found.

Annotations
@SuppressWarnings:deprecation
Since
2.13.0
getLongPropertyback to summary
public long getLongProperty(final String name, final long defaultValue)

Gets the named property as a long.

Parameters
name:String

the name of the property to look up

defaultValue:long

the default value to use if the property is undefined

Returns:long

the parsed long value of the property or defaultValue if it was undefined or could not be parsed.

getLongPropertyback to summary
public Long getLongProperty(final String[] prefixes, final String key, final Supplier<Long> supplier)

References Deprecated

Supplier is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

Retrieves a property that may be prefixed by more than one string.

Parameters
prefixes:String[]

The array of prefixes.

key:String

The key to locate.

supplier:Supplier<Long>

The method to call to derive the default value. If the value is null, null will be returned if no property is found.

Returns:Long

The value or null if it is not found.

Annotations
@SuppressWarnings:deprecation
Since
2.13.0
getPropertiesback to summary
public static PropertiesUtil getProperties()

Returns the PropertiesUtil used by Log4j.

Returns:PropertiesUtil

the main Log4j PropertiesUtil instance.

getStringPropertyback to summary
public String getStringProperty(final String[] prefixes, final String key, final Supplier<String> supplier)

References Deprecated

Supplier is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

Retrieves a property that may be prefixed by more than one string.

Parameters
prefixes:String[]

The array of prefixes.

key:String

The key to locate.

supplier:Supplier<String>

The method to call to derive the default value. If the value is null, null will be returned if no property is found.

Returns:String

The value or null if it is not found.

Annotations
@SuppressWarnings:deprecation
Since
2.13.0
getStringPropertyback to summary
public String getStringProperty(final String name)

Gets the named property as a String.

Parameters
name:String

the name of the property to look up

Returns:String

the String value of the property or null if undefined.

getStringPropertyback to summary
public String getStringProperty(final String name, final String defaultValue)

Gets the named property as a String.

Parameters
name:String

the name of the property to look up

defaultValue:String

the default value to use if the property is undefined

Returns:String

the String value of the property or defaultValue if undefined.

getSystemPropertiesback to summary
public static Properties getSystemProperties()

Return the system properties or an empty Properties object if an error occurs.

Returns:Properties

The system properties.

hasPropertyback to summary
public boolean hasProperty(final String name)

Returns true if the specified property is defined, regardless of its value (it may not have a value).

Parameters
name:String

the name of the property to verify

Returns:boolean

true if the specified property is defined, regardless of its value

isOsWindowsback to summary
public boolean isOsWindows()

Returns true if system properties tell us we are running on Windows.

Returns:boolean

true if system properties tell us we are running on Windows.

loadCloseback to summary
pack-priv static Properties loadClose(final InputStream in, final Object source)

Loads and closes the given property input stream. If an error occurs, log to the status logger.

Parameters
in:InputStream

a property input stream.

source:Object

a source object describing the source, like a resource string or a URL.

Returns:Properties

a new Properties object

partitionOnCommonPrefixesback to summary
public static Map<String, Properties> partitionOnCommonPrefixes(final Properties properties)

Partitions a properties map based on common key prefixes up to the first period.

Parameters
properties:Properties

properties to partition

Returns:Map<String, Properties>

the partitioned properties where each key is the common prefix (minus the period) and the values are new property maps without the prefix and period in the key

Since
2.6
partitionOnCommonPrefixesback to summary
public static Map<String, Properties> partitionOnCommonPrefixes(final Properties properties, final boolean includeBaseKey)

Partitions a properties map based on common key prefixes up to the first period.

Parameters
properties:Properties

properties to partition

includeBaseKey:boolean

when true if a key exists with no '.' the key will be included.

Returns:Map<String, Properties>

the partitioned properties where each key is the common prefix (minus the period) and the values are new property maps without the prefix and period in the key

Since
2.17.2
reloadback to summary
public void reload()

Reloads all properties. This is primarily useful for unit tests.

Since
2.10.0
org.apache.logging.log4j.util back to summary

private final Class PropertiesUtil.Environment

extends Object
Class Inheritance
Provides support for looking up global configuration properties via environment variables, property files, and system properties, in three variations:

Normalized: all log4j-related prefixes removed, remaining property is camelCased with a log4j2 prefix for property files and system properties, or follows a LOG4J_FOO_BAR format for environment variables.

Legacy: the original property name as defined in the source pre-2.10.0.

Tokenized: loose matching based on word boundaries.

Since
2.10.0

Field Summary

Modifier and TypeField and Description
private final Map<String, String>
literal

Maps a key to its value or the value of its normalization in the lowest priority source that contains it.

private final Set<PropertySource>
sources

private final Map<List<CharSequence>, String>
tokenized

Constructor Summary

AccessConstructor and Description
private
Environment(final PropertySource propertySource)

Method Summary

Modifier and TypeMethod and Description
public void
addPropertySource(final PropertySource
The PropertySource to add.
propertySource)

Allow a PropertySource to be added.

private boolean
containsKey(final String key)

private String
get(final String key)

private synchronized void
reload()

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

literalback to summary
private final Map<String, String> literal

Maps a key to its value or the value of its normalization in the lowest priority source that contains it.

sourcesback to summary
private final Set<PropertySource> sources
tokenizedback to summary
private final Map<List<CharSequence>, String> tokenized

Constructor Detail

Environmentback to summary
private Environment(final PropertySource propertySource)

Method Detail

addPropertySourceback to summary
public void addPropertySource(final PropertySource propertySource)

Allow a PropertySource to be added.

Parameters
propertySource:PropertySource

The PropertySource to add.

containsKeyback to summary
private boolean containsKey(final String key)
getback to summary
private String get(final String key)
reloadback to summary
private synchronized void reload()
org.apache.logging.log4j.util back to summary

private final Enum PropertiesUtil.TimeUnit

extends Enum<PropertiesUtil.TimeUnit>
Class Inheritance

Field Summary

Modifier and TypeField and Description
public static final PropertiesUtil.TimeUnit
DAYS

private final String[]
descriptions

public static final PropertiesUtil.TimeUnit
HOURS

public static final PropertiesUtil.TimeUnit
MICROS

public static final PropertiesUtil.TimeUnit
MILLIS

public static final PropertiesUtil.TimeUnit
MINUTES

public static final PropertiesUtil.TimeUnit
NANOS

public static final PropertiesUtil.TimeUnit
SECONDS

private final ChronoUnit
timeUnit

Constructor Summary

AccessConstructor and Description
private
TimeUnit(final String descriptions, final ChronoUnit timeUnit)

Method Summary

Modifier and TypeMethod and Description
pack-priv static Duration
getDuration(final String time)

public static PropertiesUtil.TimeUnit
valueOf(String name)

public static PropertiesUtil.TimeUnit[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

DAYSback to summary
public static final PropertiesUtil.TimeUnit DAYS
descriptionsback to summary
private final String[] descriptions
Annotations
@SuppressWarnings:ImmutableEnumChecker
HOURSback to summary
public static final PropertiesUtil.TimeUnit HOURS
MICROSback to summary
public static final PropertiesUtil.TimeUnit MICROS
MILLISback to summary
public static final PropertiesUtil.TimeUnit MILLIS
MINUTESback to summary
public static final PropertiesUtil.TimeUnit MINUTES
NANOSback to summary
public static final PropertiesUtil.TimeUnit NANOS
SECONDSback to summary
public static final PropertiesUtil.TimeUnit SECONDS
timeUnitback to summary
private final ChronoUnit timeUnit

Constructor Detail

TimeUnitback to summary
private TimeUnit(final String descriptions, final ChronoUnit timeUnit)

Method Detail

getDurationback to summary
pack-priv static Duration getDuration(final String time)
valueOfback to summary
public static PropertiesUtil.TimeUnit valueOf(String name)
valuesback to summary
public static PropertiesUtil.TimeUnit[] values()