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 can have parse/include directives) and using separate files for defining Velocity variables.

Variables

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.

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.

Any .variables or .properties file can also be specified using the setVariablesFile(Path) method.

In addition, variables can be specified as system properties or environment variables. A variable defined that way takes precedence over a variable defined in a file (system properties coming first).

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 equally):

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.

Author:

Pascal Essiembre

Constructor Summary

Constructors

Constructor	Description
ConfigurationLoader()	Constructor.

Method Summary

Modifier and Type	Method	Description
protected VelocityContext	createDefaultContext()
protected VelocityEngine	createVelocityEngine()
<T> T	loadFromXML(Path configFile)	Loads an XML configuration file and populates a new object represented by the given "class" attribute found on XML root element.
<T> T	loadFromXML(Path configFile, Class<T> objClass)	Loads an XML configuration file and populates a new object represented by the given class.
<T> T	loadFromXML(Path configFile, Class<T> objClass, ErrorHandler errorHandler)	Loads an XML configuration file and populates a new object represented by the given class.
void	loadFromXML(Path configFile, Object object)	Loads an XML configuration file and populates a given object.
void	loadFromXML(Path configFile, Object object, ErrorHandler errorHandler)	Loads an XML configuration file and populates a given object.
<T> T	loadFromXML(Path configFile, ErrorHandler errorHandler)	Loads an XML configuration file and populates a new object represented by the given "class" attribute found on XML root element.
String	loadString(Path configFile)	Loads a configuration file as a string.
XML	loadXML(Path configFile)	Loads an XML configuration file.
XML	loadXML(Path configFile, ErrorHandler errorHandler)	Loads an XML configuration file.
ConfigurationLoader	setVariablesFile(Path variablesFile)	Sets a variables file.

Methods inherited from class java.lang.Object

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

Constructor Detail

ConfigurationLoader

public ConfigurationLoader()

Constructor.

Method Detail

setVariablesFile

public ConfigurationLoader setVariablesFile(Path variablesFile)

Sets a variables file. See class documentation for details.

Parameters:

variablesFile - variables file

Returns:

this instance

Since:

2.0.0

loadXML

public XML loadXML(Path configFile)

Loads an XML configuration file.

Parameters:

configFile - XML configuration file

Returns:

XML

Since:

2.0.0

loadXML

public XML loadXML(Path configFile,
                   ErrorHandler errorHandler)

Loads an XML configuration file.

Parameters:

configFile - XML configuration file

errorHandler - XML error handler

Returns:

XML

Since:

2.0.0

loadFromXML

public <T> T loadFromXML(Path configFile)

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

public <T> T loadFromXML(Path configFile,
                         ErrorHandler errorHandler)

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

public <T> T loadFromXML(Path configFile,
                         Class<T> objClass)

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

public <T> T loadFromXML(Path configFile,
                         Class<T> objClass,
                         ErrorHandler errorHandler)

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

public void loadFromXML(Path configFile,
                        Object object)

Loads an XML configuration file and populates a given object.

Parameters:

configFile - XML configuration file

object - object to populate

Since:

2.0.0

loadFromXML

public void loadFromXML(Path configFile,
                        Object object,
                        ErrorHandler errorHandler)

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

public String loadString(Path configFile)

Loads a configuration file as a string.

Parameters:

configFile - configuration file

Returns:

configuration as string

Since:

2.0.0

createDefaultContext

protected VelocityContext createDefaultContext()

createVelocityEngine

protected VelocityEngine createVelocityEngine()