Configuration

What's being documented

This documents the conf-helper library in ambra (used by ambra and cas). Mulgara and Fedora use their own configuration setup.

The most up to date documentation is hopefully in the code too:

source:head/plos/libs/conf-helper/src/main/java/org/plos/configuration/ConfigurationStore.java

Layers

Configuration consists of a layered set of configuration files where configuration in a higher layer overrides those of the lower layers. Starting from the lowest layer, configuration consists of:

How to add new configuration elements

Using conf-helper in a webapp

The [source:head/plos/libs/conf-helper/src/main/java/org/plos/configuration/WebAppListener.java WebAppListener?] must be the first listener in the web.xml. For example: 

  <listener>
    <listener-class>org.plos.configuration.WebAppListener</listener-class>
  </listener>

(The only exception is for ambra, if using the org.plos.bootstrap.MasterWebAppListener, it automatically loads the conf-helper WebAppListener.)

If you want to use a config file other than /etc/topaz/ambra.xml, also add the following to your web.xml: 

  <context-param>
    <param-name>org.plos.configuration</param-name>
    <param-value>file:/etc/topaz/cas.xml</param-value>
  </context-param>

Using conf-helper in a stand-alone tool

The easiest way is to call ConfigurationStore.getInstance().loadDefaultConfiguraiton(). It will use global-defaults.xml and any org.plos.configuration.defaults.xml in the current classpath. Only after doing this can you call !ConfigurationStore.getInstance().getConfiguraiton() to use the commons-config [http://jakarta.apache.org/commons/configuration/apidocs_1.2/org/apache/commons/configuration/Configuration.html Configuration] object.

Using conf-helper in spring

Use the [source:head/plos/libs/conf-helper/src/main/java/org/plos/configuration/SpringPlaceholderConfigurer.java SpringPlaceholderConfigurer?]. Add it to your context somehow via (call this file propertyConfigurer.xml): 

<?xml version="1.0" encoding="UTF-8"?>
<beans default-autowire="autodetect"
       xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:util="http://www.springframework.org/schema/util"
       xmlns:aop="http://www.springframework.org/schema/aop"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans 
         http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
       http://www.springframework.org/schema/util 
         http://www.springframework.org/schema/util/spring-util-2.0.xsd
       http://www.springframework.org/schema/aop 
         http://www.springframework.org/schema/aop/spring-aop-2.0.xsd">

  <bean id="propertyConfigurer" class="org.plos.configuration.SpringPlaceholderConfigurer"/>
</beans>

Then configure spring in your web.xml: 

  <context-param>
    <param-name>contextConfigLocation</param-name>
    <param-value>/WEB-INF/propertyConfigurer.xml /WEB-INF/myContext.xml</param-value>
  </context-param>

And you will be able to use the ${...} syntax in your spring context to reference any commons-config parameters.

Be sure to also load the conf-helper WebAppListener FIRST in your web.xml.

Using conf-helper in freemarker

Assuming you've loaded the conf-helper into your webapp via the WebAppListener, a variable called config is added to the application context. You can use this to retrieve commons-config elements via the ${...} notation. (For example, ${config.universe.age})

Using conf-helper in xacml policies

Assuming you've loaded the conf-helper into your webapp and PDPConfig.xml contains the attribute finder module: 

    <attributeFinderModule
      class="org.plos.xacml.finder.ConfigurationAttributeFinderModule"/>

Then the various config values can be looked up by its name as in: 

    <EnvironmentAttributeDesignator DataType="http://www.w3.org/2001/XMLSchema#string"
      AttributeId="topaz.models.ri"/>

For an example, see http://gandalf/trac/browser/head/plos/webapp/src/main/resources/policy/rules/permit-creator.xml