Pantheon Config

The Pantheon Config is a simple library accessing seamlessly project configuration properties. It is a thin wrapper around the Apache Commons Configuration library.

The Apache Commons Configuration library extends the use of Java properties, allowing better and richer configuration for your projects. The added features include:

• Allowing more properties of the same name (creating an array of property values). 
• Allowing variable substitution - a value of a property can be a name of another property defined in the same configuration file. 
• Allowing including one configuration file into another (a directive include). 
• Allowing more places where the project configuration file is looked for automatically (in the current directory, in the user home directory, and in the classpath). 
• Allowing also XML configuration files. 

So why not to use directly the Apache library? Why do we need a wrapper?

There are still few features that could (and were) added, and the whole configuration was made as easy as possible (but one can still access the original Apache configuration objects if fine tuning is needed):

• Getting a configuration object (an instance of the org.generationcp.core.config.Config) as a singleton. Which allows to get to the project properties from anywhere without passing anything as method parameters. 
• Finding a project configuration file by using an additional property project.configuration (in the same spirit as the log4j configuration file is looked for). 
• Adding automatically System properties into project properties (with higher precedence which allows to fine tune your run-time). 
• Adding few methods allowing to prefix some properties to be used only by specific classes. 
• Adding a method to find all matching properties. 

For all details, check the Pantheon Config API.

How to use the Pantheon Config in your project

1. Add the Pantheon Config into your project dependency file (usually the xmls/project.pom) - but check first what is the latest version:

   		<dependency>
   	<groupId>org.generationcp.tools</groupId>
   	<artifactId>pantheon-config</artifactId>
   	<version>1.1.0</version>
   	</dependency>
   	

   This will also allow to remove many dependencies that are already covered by the Pantheon Config itself. It will make your dependency files more readable and maintainable.

   The source code of this small project is available from https://svn.cropforge.org/svn/pantheon/Ceres/projects/PantheonConfig.

    

2. Create some properties in your project configuration file. A project configuration file should be either named project.properties, or its name can be given in the run-time System Java property project.configuration.

   If you are using (as you should) usual GCP Pantheon conventions, you can also let Ant copy your own project configuration file into build/classes/project.properties by using the built-time property my.project.properties. For example:

   			ant -Dmy.project.properties=/my/best/configuration.properties config
   	

3. Start using the configuration in your code. Here are few examples (more details in the Pantheon Config API):

   		import org.generationcp.core.config.Config;
   	String value1 = Config.get().getString ("name.1", "this is default value");
   	String value2 = Config.getString ("name.2", "a default", this);
   	String[] values = Config.getStrings ("name.3", "a default", this);
   	

Exploring your project configuration

Its help page (got by calling build/run/run-explore-config -help) is similar to this:

Usage:
build/run/run-any-client org.soaplab.admin.ExploreConfig [options]
where <options> are:
-h[elp]  ... print this help
-q       ... "quiet" (less verbose mode)
-stack   ... in case of any error it print the stact trace
(without this option, it prints it only when a
serious runtime error occures)
Exploring options are:
-lf   ... list all current config resources (files)
-l[a] ... list available properties,
(-la includes also System properties)
<property-name>...
... show values of the given properties
-prefix <property-name-prefix> [-class <class-name>]
... shows all properties whose names start with
'property-name-prefix', or (if given) with
'class-name'.'property-name-prefix'
Testing options are:
-f <properties-file>[,<properties-file>...]
... add properties from the given file(s)
(comma-separated list of file names)
-xml <xml-file>[,<xml-file>...]
... add properties from the given XML file(s)
(comma-separated list of file names)