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()

Class ConfigurationLoader

Variables

System Properties

Environment variables

Explicit variable files

Implicit variable files

Configuration fragments

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Details

ConfigurationLoader

Method Details

setVariablesFile

toString

toXml

toXml

toObject

toObject

loadXML

loadXML

loadFromXML

loadFromXML

loadFromXML

loadFromXML

loadFromXML

loadFromXML

loadString

builder