Package org.apache.logging.log4j.util

Class PropertiesUtil

  • public final class PropertiesUtil
extends java.lang.Object
    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 Class Summary

      Nested Classes 
      Modifier and Type Class 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:
      private static class  PropertiesUtil.TimeUnit  

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        PropertiesUtil​(java.lang.String propertiesFileName)
      Constructs a PropertiesUtil for a given properties file name on the classpath.
      private PropertiesUtil​(java.lang.String propertiesFileName, boolean useTccl)  
        PropertiesUtil​(java.util.Properties props)
      Constructs a PropertiesUtil using a given Properties object as its source of defined properties.
      (package private) PropertiesUtil​(PropertySource source)
      Constructs a PropertiesUtil for a give property source as source of additional properties.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addPropertySource​(PropertySource propertySource)
      Allows a PropertySource to be added after PropertiesUtil has been created.
      static java.util.Properties extractSubset​(java.util.Properties properties, java.lang.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.
      boolean getBooleanProperty​(java.lang.String name)
      Gets the named property as a boolean value.
      java.lang.Boolean getBooleanProperty​(java.lang.String[] prefixes, java.lang.String key, Supplier<java.lang.Boolean> supplier)
      Retrieves a property that may be prefixed by more than one string.
      boolean getBooleanProperty​(java.lang.String name, boolean defaultValue)
      Gets the named property as a boolean value.
      boolean getBooleanProperty​(java.lang.String name, boolean defaultValueIfAbsent, boolean defaultValueIfPresent)
      Gets the named property as a boolean value.
      java.nio.charset.Charset getCharsetProperty​(java.lang.String name)
      Gets the named property as a Charset value.
      java.nio.charset.Charset getCharsetProperty​(java.lang.String name, java.nio.charset.Charset defaultValue)
      Gets the named property as a Charset value.
      (package private) static java.util.ResourceBundle getCharsetsResourceBundle()  
      double getDoubleProperty​(java.lang.String name, double defaultValue)
      Gets the named property as a double.
      java.time.Duration getDurationProperty​(java.lang.String[] prefixes, java.lang.String key, Supplier<java.time.Duration> supplier)
      Retrieves a property that may be prefixed by more than one string.
      java.time.Duration getDurationProperty​(java.lang.String name, java.time.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.
      java.lang.Integer getIntegerProperty​(java.lang.String[] prefixes, java.lang.String key, Supplier<java.lang.Integer> supplier)
      Retrieves a property that may be prefixed by more than one string.
      int getIntegerProperty​(java.lang.String name, int defaultValue)
      Gets the named property as an integer.
      java.lang.Long getLongProperty​(java.lang.String[] prefixes, java.lang.String key, Supplier<java.lang.Long> supplier)
      Retrieves a property that may be prefixed by more than one string.
      long getLongProperty​(java.lang.String name, long defaultValue)
      Gets the named property as a long.
      static PropertiesUtil getProperties()
      Returns the PropertiesUtil used by Log4j.
      java.lang.String getStringProperty​(java.lang.String name)
      Gets the named property as a String.
      java.lang.String getStringProperty​(java.lang.String[] prefixes, java.lang.String key, Supplier<java.lang.String> supplier)
      Retrieves a property that may be prefixed by more than one string.
      java.lang.String getStringProperty​(java.lang.String name, java.lang.String defaultValue)
      Gets the named property as a String.
      static java.util.Properties getSystemProperties()
      Return the system properties or an empty Properties object if an error occurs.
      boolean hasProperty​(java.lang.String name)
      Returns true if the specified property is defined, regardless of its value (it may not have a value).
      boolean isOsWindows()
      Returns true if system properties tell us we are running on Windows.
      (package private) static java.util.Properties loadClose​(java.io.InputStream in, java.lang.Object source)
      Loads and closes the given property input stream.
      static java.util.Map<java.lang.String,​java.util.Properties> partitionOnCommonPrefixes​(java.util.Properties properties)
      Partitions a properties map based on common key prefixes up to the first period.
      static java.util.Map<java.lang.String,​java.util.Properties> partitionOnCommonPrefixes​(java.util.Properties properties, boolean includeBaseKey)
      Partitions a properties map based on common key prefixes up to the first period.
      void reload()
      Reloads all properties.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • PropertiesUtil

        public PropertiesUtil​(java.util.Properties props)
        Constructs a PropertiesUtil using a given Properties object as its source of defined properties.
        Parameters:
        props - the Properties to use by default

      • PropertiesUtil

        public PropertiesUtil​(java.lang.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 - the location of properties file to load

      • PropertiesUtil

        private PropertiesUtil​(java.lang.String propertiesFileName,
                       boolean useTccl)

      • PropertiesUtil

        PropertiesUtil​(PropertySource source)
        Constructs a PropertiesUtil for a give property source as source of additional properties.
        Parameters:
        source - a property source

    • Method Detail

      • loadClose

        static java.util.Properties loadClose​(java.io.InputStream in,
                                      java.lang.Object source)
        Loads and closes the given property input stream. If an error occurs, log to the status logger.
        Parameters:
        in - a property input stream.
        source - a source object describing the source, like a resource string or a URL.
        Returns:
        a new Properties object

      • getProperties

        public static PropertiesUtil getProperties()
        Returns the PropertiesUtil used by Log4j.
        Returns:
        the main Log4j PropertiesUtil instance.

      • addPropertySource

        public void addPropertySource​(PropertySource propertySource)
        Allows a PropertySource to be added after PropertiesUtil has been created.
        Parameters:
        propertySource - the PropertySource to add.

      • hasProperty

        public boolean hasProperty​(java.lang.String name)
        Returns true if the specified property is defined, regardless of its value (it may not have a value).
        Parameters:
        name - the name of the property to verify
        Returns:
        true if the specified property is defined, regardless of its value

      • getBooleanProperty

        public boolean getBooleanProperty​(java.lang.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 - the name of the property to look up
        Returns:
        the boolean value of the property or false if undefined.

      • getBooleanProperty

        public boolean getBooleanProperty​(java.lang.String name,
                                  boolean defaultValue)
        Gets the named property as a boolean value.
        Parameters:
        name - the name of the property to look up
        defaultValue - the default value to use if the property is undefined
        Returns:
        the boolean value of the property or defaultValue if undefined.

      • getBooleanProperty

        public boolean getBooleanProperty​(java.lang.String name,
                                  boolean defaultValueIfAbsent,
                                  boolean defaultValueIfPresent)
        Gets the named property as a boolean value.
        Parameters:
        name - the name of the property to look up
        defaultValueIfAbsent - the default value to use if the property is undefined
        defaultValueIfPresent - the default value to use if the property is defined but not assigned
        Returns:
        the boolean value of the property or defaultValue if undefined.

      • getBooleanProperty

        public java.lang.Boolean getBooleanProperty​(java.lang.String[] prefixes,
                                            java.lang.String key,
                                            Supplier<java.lang.Boolean> supplier)
        Retrieves a property that may be prefixed by more than one string.
        Parameters:
        prefixes - The array of prefixes.
        key - The key to locate.
        supplier - The method to call to derive the default value. If the value is null, null will be returned if no property is found.
        Returns:
        The value or null if it is not found.
        Since:
        2.13.0

      • getCharsetProperty

        public java.nio.charset.Charset getCharsetProperty​(java.lang.String name)
        Gets the named property as a Charset value.
        Parameters:
        name - the name of the property to look up
        Returns:
        the Charset value of the property or Charset.defaultCharset() if undefined.

      • getCharsetProperty

        public java.nio.charset.Charset getCharsetProperty​(java.lang.String name,
                                                   java.nio.charset.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 - the name of the property to look up
        defaultValue - the default value to use if the property is undefined
        Returns:
        the Charset value of the property or defaultValue if undefined.

      • getDoubleProperty

        public double getDoubleProperty​(java.lang.String name,
                                double defaultValue)
        Gets the named property as a double.
        Parameters:
        name - the name of the property to look up
        defaultValue - the default value to use if the property is undefined
        Returns:
        the parsed double value of the property or defaultValue if it was undefined or could not be parsed.

      • getIntegerProperty

        public int getIntegerProperty​(java.lang.String name,
                              int defaultValue)
        Gets the named property as an integer.
        Parameters:
        name - the name of the property to look up
        defaultValue - the default value to use if the property is undefined
        Returns:
        the parsed integer value of the property or defaultValue if it was undefined or could not be parsed.

      • getIntegerProperty

        public java.lang.Integer getIntegerProperty​(java.lang.String[] prefixes,
                                            java.lang.String key,
                                            Supplier<java.lang.Integer> supplier)
        Retrieves a property that may be prefixed by more than one string.
        Parameters:
        prefixes - The array of prefixes.
        key - The key to locate.
        supplier - The method to call to derive the default value. If the value is null, null will be returned if no property is found.
        Returns:
        The value or null if it is not found.
        Since:
        2.13.0

      • getLongProperty

        public long getLongProperty​(java.lang.String name,
                            long defaultValue)
        Gets the named property as a long.
        Parameters:
        name - the name of the property to look up
        defaultValue - the default value to use if the property is undefined
        Returns:
        the parsed long value of the property or defaultValue if it was undefined or could not be parsed.

      • getLongProperty

        public java.lang.Long getLongProperty​(java.lang.String[] prefixes,
                                      java.lang.String key,
                                      Supplier<java.lang.Long> supplier)
        Retrieves a property that may be prefixed by more than one string.
        Parameters:
        prefixes - The array of prefixes.
        key - The key to locate.
        supplier - The method to call to derive the default value. If the value is null, null will be returned if no property is found.
        Returns:
        The value or null if it is not found.
        Since:
        2.13.0

      • getDurationProperty

        public java.time.Duration getDurationProperty​(java.lang.String name,
                                              java.time.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 - The property name.
        defaultValue - The default value.
        Returns:
        The value of the String as a Duration or the default value, which may be null.
        Since:
        2.13.0

      • getDurationProperty

        public java.time.Duration getDurationProperty​(java.lang.String[] prefixes,
                                              java.lang.String key,
                                              Supplier<java.time.Duration> supplier)
        Retrieves a property that may be prefixed by more than one string.
        Parameters:
        prefixes - The array of prefixes.
        key - The key to locate.
        supplier - The method to call to derive the default value. If the value is null, null will be returned if no property is found.
        Returns:
        The value or null if it is not found.
        Since:
        2.13.0

      • getStringProperty

        public java.lang.String getStringProperty​(java.lang.String[] prefixes,
                                          java.lang.String key,
                                          Supplier<java.lang.String> supplier)
        Retrieves a property that may be prefixed by more than one string.
        Parameters:
        prefixes - The array of prefixes.
        key - The key to locate.
        supplier - The method to call to derive the default value. If the value is null, null will be returned if no property is found.
        Returns:
        The value or null if it is not found.
        Since:
        2.13.0

      • getStringProperty

        public java.lang.String getStringProperty​(java.lang.String name)
        Gets the named property as a String.
        Parameters:
        name - the name of the property to look up
        Returns:
        the String value of the property or null if undefined.

      • getStringProperty

        public java.lang.String getStringProperty​(java.lang.String name,
                                          java.lang.String defaultValue)
        Gets the named property as a String.
        Parameters:
        name - the name of the property to look up
        defaultValue - the default value to use if the property is undefined
        Returns:
        the String value of the property or defaultValue if undefined.

      • getSystemProperties

        public static java.util.Properties getSystemProperties()
        Return the system properties or an empty Properties object if an error occurs.
        Returns:
        The system properties.

      • reload

        public void reload()
        Reloads all properties. This is primarily useful for unit tests.
        Since:
        2.10.0

      • extractSubset

        public static java.util.Properties extractSubset​(java.util.Properties properties,
                                                 java.lang.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 - The Properties to evaluate.
        prefix - The prefix to extract.
        Returns:
        The subset of properties.

      • getCharsetsResourceBundle

        static java.util.ResourceBundle getCharsetsResourceBundle()

      • partitionOnCommonPrefixes

        public static java.util.Map<java.lang.String,​java.util.Properties> partitionOnCommonPrefixes​(java.util.Properties properties)
        Partitions a properties map based on common key prefixes up to the first period.
        Parameters:
        properties - properties to partition
        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
        Since:
        2.6

      • partitionOnCommonPrefixes

        public static java.util.Map<java.lang.String,​java.util.Properties> partitionOnCommonPrefixes​(java.util.Properties properties,
                                                                                                   boolean includeBaseKey)
        Partitions a properties map based on common key prefixes up to the first period.
        Parameters:
        properties - properties to partition
        includeBaseKey - when true if a key exists with no '.' the key will be included.
        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
        Since:
        2.17.2

      • isOsWindows

        public boolean isOsWindows()
        Returns true if system properties tell us we are running on Windows.
        Returns:
        true if system properties tell us we are running on Windows.