Class Configuration

java.lang.Object
org.xhtmlrenderer.util.Configuration

public class Configuration extends Object

Stores runtime configuration information for application parameters that may vary on restarting. This implements the Singleton pattern, but through static methods. That is, the first time Configuration is used, the properties are loaded into the Singleton instance. Subsequent calls to valueFor() retrieve values from the Singleton. To look up a property, use valueFor(String).

Properties may be overridden using a second properties file, or individually using System properties specified on the command line. To override using a second properties file, specify the System property xr-conf. This should be the location of the second file relative to the CLASSPATH, or else a file path, e.g.

java -Dxr-conf=resources/conf/my-props.conf

You can also place your override properties file in your user home directory, in

${user.home}/.flyingsaucer/local.xhtmlrenderer.conf

To override a property using the System properties, just re-define the property on the command line. e.g.

java -Dxr.property-name=new_value

The order in which these will be read is: default properties (bundled with the core, in the jar; override configuration properties; properties file in user.home; and system properties.

You can override as many properties as you like.

Note that overrides are driven by the property names in the default configuration file. Specifying a property name not in that file will have no effect--the property will not be loaded or available for lookup. Configuration is NOT used to control logging levels or output; see LogStartupConfig.

There are convenience conversion method for all the primitive types, in methods like valueAsInt(String, int). A default must always be provided for these methods. The default is returned if the value is not found, or if the conversion from String fails. If the value is not present, or the conversion fails, a warning message is written to the log.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private @Nullable Logger
    Logger we use internally related to configuration.
    private static final org.slf4j.Logger
     
    private Level
    The log Level for Configuration messages; taken from show-config System property.
    private final Properties
    Our backing data store of properties.
    private static final String
    The location of our default properties file; must be on the CLASSPATH.
    private static final Configuration
    The Singleton instance of the class.
    private final List<LogRecord>
    List of LogRecords for messages from Configuration startup; used to hold these temporarily as we can't use XRLog while starting up, as it depends on Configuration.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Default constructor.
  • Method Summary

    Modifier and Type
    Method
    Description
    private void
    fine(String msg)
    Used internally to log a message about the class at level FINE
    private void
    Used internally to log a message about the class at level FINER
    private @Nullable String
     
    private @Nullable String
     
    private @Nullable String
     
    private void
     
    private void
    info(String msg)
    Used internally to log a message about the class at level INFO
    private static Configuration
     
    static boolean
    isFalse(String key, boolean defaultVal)
    Returns true if the value is not "true" (ignores case), or the default provided value if not found or if the value is not a valid boolean (true or false, ignores case).
    static boolean
    isTrue(String key, boolean defaultVal)
    Returns true if the value is "true" (ignores case), or the default provided value if not found or if the value is not a valid boolean (true or false, ignores case).
    Returns all configuration keys that start with prefix.
    private Properties
    Loads the default set of properties, which may be overridden.
    private void
    Loads overriding property values from a second configuration file; this is optional.
    private void
    Loads overriding property values from a System properties; this is optional.
    private void
    Writes a log of loaded properties to the "plumbing.init" Logger.
    private Properties
    Returns a Properties instance filled with values of last resort--in case we can't read default properties file for some reason; this is to prevent Configuration init from throwing any exceptions, or ending up with a completely empty configuration instance.
    private void
    println(Level level, String msg)
    Used internally for logging status/info about the class.
    static void
    Sets the logger which we use for Configuration-related logging.
    private static Collection<String>
    sortedKeys(Properties properties)
     
    static int
    valueAsByte(String key, byte defaultVal)
    Returns the value for key in the Configuration as a byte, or the default provided value if not found or if the value is not a valid byte.
    static char
    valueAsChar(String key, char defaultVal)
    Returns the value for key in the Configuration as a character, or a default value if not found.
    static double
    valueAsDouble(String key, double defaultVal)
    Returns the value for key in the Configuration as a double, or the default provided value if not found or if the value is not a valid double.
    static float
    valueAsFloat(String key, float defaultVal)
    Returns the value for key in the Configuration as a float, or the default provided value if not found or if the value is not a valid float.
    static int
    valueAsInt(String key, int defaultVal)
    Returns the value for key in the Configuration as an integer, or a default value if not found or if the value is not a valid integer.
    static long
    valueAsLong(String key, long defaultVal)
    Returns the value for key in the Configurations a long, or the default provided value if not found or if the value is not a valid long.
    static int
    valueAsShort(String key, short defaultVal)
    Returns the value for key in the Configuration as a short, or the default provided value if not found or if the value is not a valid short.
    static @Nullable String
    Returns the value for key in the Configuration.
    static String
    valueFor(String key, String defaultVal)
    Returns the value for key in the Configuration, or the default provided value if not found.
    static Object
    valueFromClassConstant(String key, Object defaultValue)
    Given a property, resolves the value to a public constant field on some class, where the field is of type Object.
    private void
    Used internally to log a message about the class at level WARNING
    private void
    Used internally to log a message about the class at level WARNING, in case an exception was thrown

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • log

      private static final org.slf4j.Logger log
    • properties

      private final Properties properties
      Our backing data store of properties.
    • logLevel

      private Level logLevel
      The log Level for Configuration messages; taken from show-config System property.
    • sInstance

      private static final Configuration sInstance
      The Singleton instance of the class.
    • startupLogRecords

      private final List<LogRecord> startupLogRecords
      List of LogRecords for messages from Configuration startup; used to hold these temporarily as we can't use XRLog while starting up, as it depends on Configuration.
    • configLogger

      private @Nullable Logger configLogger
      Logger we use internally related to configuration.
    • SF_FILE_NAME

      private static final String SF_FILE_NAME
      The location of our default properties file; must be on the CLASSPATH.
      See Also:
  • Constructor Details

    • Configuration

      private Configuration()
      Default constructor. Will parse default configuration file, system properties, override properties, etc. and result in a usable Configuration instance.
      Throws:
      RuntimeException - if any stage of loading configuration results in an Exception. This could happen, for example, if the default configuration file was not readable.
  • Method Details

    • handleUnexpectedExceptionOnInit

      private void handleUnexpectedExceptionOnInit(Exception e)
    • setConfigLogger

      public static void setConfigLogger(Logger logger)
      Sets the logger which we use for Configuration-related logging. Before this is called the first time, all internal log records are queued up; they are flushed to the logger when this method is first called. Afterwards, all log events are written to this logger. This queueing behavior helps avoid order-of-operations bugs related to loading configuration information related to logging.
      Parameters:
      logger - Logger used for Configuration-related messages
    • println

      private void println(Level level, String msg)
      Used internally for logging status/info about the class.
      Parameters:
      level - the logging level to record the message at
      msg - the message to log
    • info

      private void info(String msg)
      Used internally to log a message about the class at level INFO
      Parameters:
      msg - message to log
    • warning

      private void warning(String msg)
      Used internally to log a message about the class at level WARNING
      Parameters:
      msg - message to log
    • warning

      private void warning(String msg, Throwable th)
      Used internally to log a message about the class at level WARNING, in case an exception was thrown
      Parameters:
      msg - message to log
      th - the exception to report
    • fine

      private void fine(String msg)
      Used internally to log a message about the class at level FINE
      Parameters:
      msg - message to log
    • finer

      private void finer(String msg)
      Used internally to log a message about the class at level FINER
      Parameters:
      msg - message to log
    • loadDefaultProperties

      @CheckReturnValue private Properties loadDefaultProperties()
      Loads the default set of properties, which may be overridden.
    • loadOverrideProperties

      private void loadOverrideProperties(String uri)
      Loads overriding property values from a second configuration file; this is optional. See class documentation.
      Parameters:
      uri - Path to the file, or classpath URL, where properties are defined.
    • getSystemPropertyOverrideFileName

      private @Nullable String getSystemPropertyOverrideFileName()
    • getUserHomeOverrideFileName

      private @Nullable String getUserHomeOverrideFileName()
    • sortedKeys

      private static Collection<String> sortedKeys(Properties properties)
    • loadSystemProperties

      private void loadSystemProperties()
      Loads overriding property values from a System properties; this is optional. See class documentation.
    • logAfterLoad

      private void logAfterLoad()
      Writes a log of loaded properties to the "plumbing.init" Logger.
    • valueFor

      public static @Nullable String valueFor(String key)
      Returns the value for key in the Configuration. A warning is issued to the log if the property is not defined.
      Parameters:
      key - Name of the property.
      Returns:
      Value assigned to the key, as a String.
    • valueAsByte

      public static int valueAsByte(String key, byte defaultVal)
      Returns the value for key in the Configuration as a byte, or the default provided value if not found or if the value is not a valid byte. A warning is issued to the log if the property is not defined, or if the conversion from String fails.
      Parameters:
      key - Name of the property.
      defaultVal - Default value to return
      Returns:
      Value assigned to the key, as a String.
    • valueAsShort

      public static int valueAsShort(String key, short defaultVal)
      Returns the value for key in the Configuration as a short, or the default provided value if not found or if the value is not a valid short. A warning is issued to the log if the property is not defined, or if the conversion from String fails.
      Parameters:
      key - Name of the property.
      defaultVal - Default value to return
      Returns:
      Value assigned to the key, as a String.
    • valueAsInt

      public static int valueAsInt(String key, int defaultVal)
      Returns the value for key in the Configuration as an integer, or a default value if not found or if the value is not a valid integer. A warning is issued to the log if the property is not defined, or if the conversion from String fails.
      Parameters:
      key - Name of the property.
      defaultVal - Default value to return
      Returns:
      Value assigned to the key, as a String.
    • valueAsChar

      public static char valueAsChar(String key, char defaultVal)
      Returns the value for key in the Configuration as a character, or a default value if not found. A warning is issued to the log if the property is not defined, or if the configuration value is too long to be a char. If the configuration value is longer than a single character, only the first character is returned.
      Parameters:
      key - Name of the property
      defaultVal - Default value to return
      Returns:
      Value assigned to the key, as a character
    • valueAsLong

      public static long valueAsLong(String key, long defaultVal)
      Returns the value for key in the Configurations a long, or the default provided value if not found or if the value is not a valid long. A warning is issued to the log if the property is not defined, or if the conversion from String fails.
      Parameters:
      key - Name of the property.
      defaultVal - Default value to return
      Returns:
      Value assigned to the key, as a String.
    • valueAsFloat

      public static float valueAsFloat(String key, float defaultVal)
      Returns the value for key in the Configuration as a float, or the default provided value if not found or if the value is not a valid float. A warning is issued to the log if the property is not defined, or if the conversion from String fails.
      Parameters:
      key - Name of the property.
      defaultVal - Default value to return
      Returns:
      Value assigned to the key, as a String.
    • valueAsDouble

      public static double valueAsDouble(String key, double defaultVal)
      Returns the value for key in the Configuration as a double, or the default provided value if not found or if the value is not a valid double. A warning is issued to the log if the property is not defined, or if the conversion from String fails.
      Parameters:
      key - Name of the property.
      defaultVal - Default value to return
      Returns:
      Value assigned to the key, as a String.
    • valueFor

      public static String valueFor(String key, String defaultVal)
      Returns the value for key in the Configuration, or the default provided value if not found. A warning is issued to the log if the property is not defined, and if the default is null.
      Parameters:
      key - Name of the property.
      defaultVal - Default value to return
      Returns:
      Value assigned to the key, as a String.
    • keysByPrefix

      public static Iterator<String> keysByPrefix(String prefix)
      Returns all configuration keys that start with prefix. Iterator will be empty if no such keys are found.
      Parameters:
      prefix - Prefix to filter on. No regex.
    • isTrue

      public static boolean isTrue(String key, boolean defaultVal)
      Returns true if the value is "true" (ignores case), or the default provided value if not found or if the value is not a valid boolean (true or false, ignores case). A warning is issued to the log if the property is not defined, and if the default is null.
      Parameters:
      key - Name of the property.
      defaultVal - Default value to return
      Returns:
      Value assigned to the key, as a String.
    • isFalse

      public static boolean isFalse(String key, boolean defaultVal)
      Returns true if the value is not "true" (ignores case), or the default provided value if not found or if the value is not a valid boolean (true or false, ignores case). A warning is issued to the log if the property is not defined, or the value is not a valid boolean.
      Parameters:
      key - Name of the property.
      defaultVal - Default value to return
      Returns:
      Value assigned to the key, as a String.
    • instance

      private static Configuration instance()
      Returns:
      The singleton instance of the class.
    • valueFromClassConstant

      public static Object valueFromClassConstant(String key, Object defaultValue)
      Given a property, resolves the value to a public constant field on some class, where the field is of type Object. The property value must the FQN of the class and field, e.g. aKey=java.awt.RenderingHints.VALUE_INTERPOLATION_NEAREST_NEIGHBOR will return the value of the VALUE_INTERPOLATION_NEAREST_NEIGHBOR constant on the RendingHints class.
      Parameters:
      key - Name of the property
      defaultValue - Returned in case of error.
      Returns:
      Value of the constant, or defaultValue in case of error.
    • newFallbackProperties

      @CheckReturnValue private Properties newFallbackProperties()
      Returns a Properties instance filled with values of last resort--in case we can't read default properties file for some reason; this is to prevent Configuration init from throwing any exceptions, or ending up with a completely empty configuration instance.
    • getSystemProperty

      private @Nullable String getSystemProperty(String name)