com.norconex.commons.lang.config
Class ConfigurationLoader

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

public final class ConfigurationLoader
extends Object

Class parsing a Velocity template (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 takes precedence.

Any .variables or .properties file can also be specified using the loadXML(File, File) method.

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:

 XMLConfiguration xml = ConfigurationLoader.loadXML(
         new File("C:\\sample\\myapp\\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
ConfigurationLoader()
          Constructor.
ConfigurationLoader(Properties velocityProperties)
          Constructor.
 
Method Summary
 String loadString(File configFile, File variables)
          Loads a configuration file as a string.
 XMLConfiguration loadXML(File configFile)
          Loads a configuration file.
 XMLConfiguration loadXML(File configFile, File variables)
          Loads a configuration file.
static XMLConfiguration loadXML(Reader in)
          This load method will return an Apache XML Configuration without any variable substitution or Velocity directives.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ConfigurationLoader

public ConfigurationLoader()
Constructor.


ConfigurationLoader

public ConfigurationLoader(Properties velocityProperties)
Constructor.

Parameters:
velocityProperties - custom properties for parsing Velocity files
Method Detail

loadXML

public XMLConfiguration loadXML(File configFile)
Loads a configuration file.

Parameters:
configFile - XML configuration file
Returns:
Apache XMLConfiguration instance

loadXML

public XMLConfiguration loadXML(File configFile,
                                File variables)
Loads a configuration file.

Parameters:
configFile - XML configuration file
variables - path to .variables or .properties file defining variables.
Returns:
Apache XMLConfiguration instance

loadString

public String loadString(File configFile,
                         File variables)
Loads a configuration file as a string.

Parameters:
configFile - configuration file
variables - path to .variables or .properties file defining variables.
Returns:
configuration as string

loadXML

public static XMLConfiguration loadXML(Reader in)
This load method will return an Apache XML Configuration without any variable substitution or Velocity directives. Velocity parsing or variable substitution.

Parameters:
in - input stream
Returns:
XMLConfiguration


Copyright © 2008-2013 Norconex Inc.. All Rights Reserved.