Package com.norconex.commons.lang.config

# Class ConfigurationLoader

java.lang.Object
com.norconex.commons.lang.config.ConfigurationLoader

public final class ConfigurationLoader extends Object

Configuration file parser using Velocity template engine which supports variables, parse/include directives, and more).

## Variables

Variables can be defined in a few different ways and will be resolved in this order precedence (first one to match):

- System properties
- Environment variables
- Java properties
- Explicit variable files
- Implicit variable files

In a configuration file, variables are referenced surrounded by curly braces and prefixed with a dollar sign. Default values can be specified by following the variable name with a vertical bar character and the value. Examples:

- `${pageTitle}` → Prints the value of a variable named "pageTitle" or nothing if no title variable is found.
- `${pageTitle|'Hello world!'}` → Prints the value of a variable named "pageTitle", or "Hello world!" if no title variable is found.

## System Properties

System properties are typically passed to the JVM at launch time with the `-D` argument. Variables defined as system properties take precedence over variables of the same name defined any other way. Character case, as well as non-alphanumeric characters have no importance in the variable resolution. For instance, all of the following are equivalent:

- `-DpageTitle`
- `-Dpagetitle`
- `-DPAGE_TITLE`

## Environment variables

Environment variables are typically set at a user account level, or operating system level. Environment variables take precedence over variable files, but not over system properties. Like system properties, character case, as well as non-alphanumeric characters have no importance in the variable resolution. For instance, all of the following are equivalent:

- `pageTitle`
- `pagetitle`
- `PAGE_TITLE`

## Explicit variable files

Any `.variables` or `.properties` file can also be specified using the `setVariablesFile(Path)` method. Since 3.0.0, any variable file without the `.properties` extension is treated as if its extension was `.variables`. The syntax for both file types is the same as described under Implicit variable files below.

## Implicit variable files

Configuration templates, whether the main template or any template included using the `#parse` directive, can have variable files attached, for which each key would become a variable in the Velocity context. A variable file must be of the same name as the template file, with one of two possible extensions: `.variables` or `.properties`. By respecting this naming condition, the variable files do not have to be explicitly specified as argument.

A `.variables` file must have keys and values separated by an equal sign, one variable per line. The key and value strings are taken literally, after trimming leading and trailing spaces.

A `.properties` file stores key/value in the way the Java programming language expects it for any `.properties` file. It is essentially the same, but has more options (e.g. multi-line support) and gotchas (e.g. must escape certain characters). Please refer to the corresponding Java API documentation for exact syntax and parsing logic.

When both `.variables` and `.properties` exist for a template, the `.properties` file variables take precedence.

## Configuration fragments

To include configuration fragments and favor reuse, use the `#include("myfile.cg")` or `#parse("myfile.cg")` directives. An include directive will include the referenced file as-is, without interpretation. A parse directive will treat the included file as a Velocity file and will interpret it (along with its variable file if any exists -- see above).

The included/parsed files are relative to the parent template, or, can be absolute paths on the host where the configuration loader is executed. Example (both Windows and UNIX path styles are supported):

Sample directory structure:

     c:\sample\
         myapp\
             runme.jar
             configs\
                  myconfig.cfg
                  myconfig.properties
         shared\
             sharedconfig.cfg
             sharedconfig.variables

Configuration file myconfig.cfg:

     <myconfig>
        <host>$host</host>
        <port>$port</port>
        #parse("../../shared/sharedconfig.cfg")
     </myconfig>

Configuration loading:

     XML xml = new ConfigurationLoader().loadXML(
             Path.get("/path/to/myconfig.cfg"));

Explanation:

When loading myconfig.cfg, the variables defined in myconfig.properties are automatically loaded and will replace the $host and $port variables. The myconfig.cfg file is also parsing a shared configuration file: sharedconfig.cfg. That file will be parsed and inserted, with its variables defined in sharedconfig.variables automatically loaded and resolved.

Other Velocity directives are supported (if-else statements, foreach loops, macros, etc.). Refer to Velocity User Guide for complete syntax and template documentation.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `ConfigurationLoader.ConfigurationLoaderBuilder`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ConfigurationLoader()`
  Deprecated.
  Use `builder()` instead.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static ConfigurationLoader.ConfigurationLoaderBuilder`
  `builder()`
  `<T> T`
  `loadFromXML(Path configFile)`
  Deprecated.
  Use `toObject(Path, Class)` instead
  `<T> T`
  `loadFromXML(Path configFile, Class<T> objClass)`
  Deprecated.
  Use `toObject(Path, Class)` instead
  `<T> T`
  `loadFromXML(Path configFile, Class<T> objClass, ErrorHandler errorHandler)`
  Deprecated.
  Use `toObject(Path, Class)` instead
  `void`
  `loadFromXML(Path configFile, Object object)`
  Deprecated.
  Use `toObject(Path, Object)` instead
  `void`
  `loadFromXML(Path configFile, Object object, ErrorHandler errorHandler)`
  Deprecated.
  Use `toObject(Path, Object)` instead
  `<T> T`
  `loadFromXML(Path configFile, ErrorHandler errorHandler)`
  Deprecated.
  Use `toObject(Path, Class)` instead
  `String`
  `loadString(Path configFile)`
  Deprecated.
  Use `toString(Path)` instead
  `Xml`
  `loadXML(Path configFile)`
  Deprecated.
  Use `toXml(Path)` instead.
  `Xml`
  `loadXML(Path configFile, ErrorHandler errorHandler)`
  Deprecated.
  Use `toXml(Path, ErrorHandler)` instead.
  `ConfigurationLoader`
  `setVariablesFile(Path variablesFile)`
  Deprecated.
  Use `ConfigurationLoader.ConfigurationLoaderBuilder.variablesFile(Path)` instead.
  `void`
  `toObject(@NonNull Path configFile, @NonNull Object object)`
  Loads an XML, JSON, or Yaml configuration file and populates the supplied object.
  `<T> T`
  `toObject(@NonNull Path configFile, Class<T> type)`
  Loads an XML, JSON, or Yaml configuration file and populates a new object represented by the given class.
  `String`
  `toString(Path configFile)`
  Loads a configuration file as a string, performing variable interpolation and handling any other Velocity directives.
  `Xml`
  `toXml(Path configFile)`
  Loads an XML configuration file into an `Xml` object, performing variable interpolation and handling any other Velocity directives.
  `Xml`
  `toXml(Path configFile, ErrorHandler errorHandler)`
  Loads an XML configuration file into an `Xml` object, performing variable interpolation and handling any other Velocity directives.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### ConfigurationLoader

    @Deprecated(since="3.0.0") public ConfigurationLoader()
    Deprecated.
    Use `builder()` instead.

- ## Method Details

  - ### setVariablesFile

    @Deprecated(since="3.0.0") public ConfigurationLoader setVariablesFile(Path variablesFile)
    Deprecated.
    Use `ConfigurationLoader.ConfigurationLoaderBuilder.variablesFile(Path)` instead.
    Sets a variables file. See class documentation for details.
    Parameters:
      `variablesFile` - variables file
    Returns:
      this instance
    Since:
      2.0.0

  - ### toString

    public String toString(Path configFile)
    Loads a configuration file as a string, performing variable interpolation and handling any other Velocity directives.
    Parameters:
      `configFile` - configuration file
    Returns:
      configuration as string
    Since:
      3.0.0, renamed from `loadString`

  - ### toXml

    public Xml toXml(Path configFile)
    Loads an XML configuration file into an `Xml` object, performing variable interpolation and handling any other Velocity directives.
    Parameters:
      `configFile` - XML configuration file
    Returns:
      XML
    Since:
      3.0.0 renamed from `loadXML(Path)`

  - ### toXml

    public Xml toXml(Path configFile, ErrorHandler errorHandler)
    Loads an XML configuration file into an `Xml` object, performing variable interpolation and handling any other Velocity directives.
    Parameters:
      `configFile` - XML configuration file
      `errorHandler` - XML error handler
    Returns:
      XML
    Since:
      3.0.0 renamed from `loadXML(Path, ErrorHandler)`

  - ### toObject

    public <T> T toObject(@NonNull @NonNull Path configFile, Class<T> type)
    Loads an XML, JSON, or Yaml configuration file and populates a new object represented by the given class. Performs variable interpolation and handling of any other Velocity directives. Validation error will throw a `ConstraintViolationException`. To disable validation specify a custom `BeanMapper` and set `skipValidation` to `true` on the mapper builder. The file format is dictated by the file extension (XML is assumed if the file has no extension).
    Type Parameters:
      `T` - type of returned object
    Parameters:
      `configFile` - configuration file
      `type` - class of the object to create and populate
    Returns:
      new object
    Since:
      3.0.0

  - ### toObject

    public void toObject(@NonNull @NonNull Path configFile, @NonNull @NonNull Object object)
    Loads an XML, JSON, or Yaml configuration file and populates the supplied object. Performs variable interpolation and handling of any other Velocity directives. Validation error will throw a `ConstraintViolationException`. To disable validation specify a custom `BeanMapper` and set `skipValidation` to `true` on the mapper builder. The file format is dictated by the file extension (XML is assumed if the file has no extension). Loads an XML configuration file and populates a given object.
    Parameters:
      `configFile` - XML configuration file
      `object` - object to populate
    Since:
      3.0.0

  - ### loadXML

    @Deprecated(since="3.0.0") public Xml loadXML(Path configFile)
    Deprecated.
    Use `toXml(Path)` instead.
    Loads an XML configuration file.
    Parameters:
      `configFile` - XML configuration file
    Returns:
      XML
    Since:
      2.0.0

  - ### loadXML

    @Deprecated(since="3.0.0") public Xml loadXML(Path configFile, ErrorHandler errorHandler)
    Deprecated.
    Use `toXml(Path, ErrorHandler)` instead.
    Loads an XML configuration file.
    Parameters:
      `configFile` - XML configuration file
      `errorHandler` - XML error handler
    Returns:
      XML
    Since:
      2.0.0

  - ### loadFromXML

    @Deprecated(since="3.0.0") public <T> T loadFromXML(Path configFile)
    Deprecated.
    Use `toObject(Path, Class)` instead
    Loads an XML configuration file and populates a new object represented by the given "class" attribute found on XML root element.
    Type Parameters:
      `T` - type of returned object
    Parameters:
      `configFile` - XML configuration file
    Returns:
      new object
    Since:
      2.0.0

  - ### loadFromXML

    @Deprecated(since="3.0.0") public <T> T loadFromXML(Path configFile, ErrorHandler errorHandler)
    Deprecated.
    Use `toObject(Path, Class)` instead
    Loads an XML configuration file and populates a new object represented by the given "class" attribute found on XML root element.
    Type Parameters:
      `T` - type of returned object
    Parameters:
      `configFile` - XML configuration file
      `errorHandler` - XML error handler
    Returns:
      new object
    Since:
      2.0.0

  - ### loadFromXML

    @Deprecated(since="3.0.0") public <T> T loadFromXML(Path configFile, Class<T> objClass)
    Deprecated.
    Use `toObject(Path, Class)` instead
    Loads an XML configuration file and populates a new object represented by the given class.
    Type Parameters:
      `T` - type of returned object
    Parameters:
      `configFile` - XML configuration file
      `objClass` - type of object to create and populate
    Returns:
      new object
    Since:
      2.0.0

  - ### loadFromXML

    @Deprecated(since="3.0.0") public <T> T loadFromXML(Path configFile, Class<T> objClass, ErrorHandler errorHandler)
    Deprecated.
    Use `toObject(Path, Class)` instead
    Loads an XML configuration file and populates a new object represented by the given class.
    Type Parameters:
      `T` - type of returned object
    Parameters:
      `configFile` - XML configuration file
      `objClass` - type of object to create and populate
      `errorHandler` - XML error handler
    Returns:
      new object
    Since:
      2.0.0

  - ### loadFromXML

    @Deprecated(since="3.0.0") public void loadFromXML(Path configFile, Object object)
    Deprecated.
    Use `toObject(Path, Object)` instead
    Loads an XML configuration file and populates a given object.
    Parameters:
      `configFile` - XML configuration file
      `object` - object to populate
    Since:
      2.0.0

  - ### loadFromXML

    @Deprecated(since="3.0.0") public void loadFromXML(Path configFile, Object object, ErrorHandler errorHandler)
    Deprecated.
    Use `toObject(Path, Object)` instead
    Loads an XML configuration file and populates a given object.
    Parameters:
      `configFile` - XML configuration file
      `object` - object to populate
      `errorHandler` - XML error handler
    Since:
      2.0.0

  - ### loadString

    @Deprecated(since="3.0.0") public String loadString(Path configFile)
    Deprecated.
    Use `toString(Path)` instead
    Loads a configuration file as a string.
    Parameters:
      `configFile` - configuration file
    Returns:
      configuration as string
    Since:
      2.0.0

  - ### builder

    public static ConfigurationLoader.ConfigurationLoaderBuilder builder()