Ambra 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:

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:

  • conf-helper/global-defaults.xml - A resource in the conf-helper library. Defines defaults for <network> and <topaz> sections.
  • ambra/configuration/defaults.xml - Every library or webapp can have one of these and it provids the defaults for elements it uses. The following defaults.xml files currently exist:
  • ambra.configuration.overrides - If this system property (or webapp context parameter in web.xml) is set, this defines a named resource or URL of a resource that is added to the configuration tree - usually supplementing and overriding settings in global-defaults.xml and defaults.xml. An example of this is the dev-mode used by the ambra-webapp.
  • file:/etc/topaz/ambra.xml (or ambra.configuration) - A set of user overrides in /etc. The name of this file can be changed for webapps that use [source:head/ambra/libs/conf-helper/src/main/java/org/topazproject/ambra/configuration/WebAppListener.java WebAppListener?] by changing web.xml or by setting the org.plos.configuration system property.
    • ambra.xml
      • Template that goes in /etc for ambra rpm.
    • cas.xml - Template
    • that goes in /etc for cas rpm.
  • System properties - System properties can override any configuration setting. Usually these are used by command-line applications.

How to add new configuration elements

Using conf-helper in a webapp

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

  <listener>
    <listener-class>org.topazproject.ambra.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>ambra.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 ambra.configuration.defaults.xml in the current classpath. Only after doing this can you call !ConfigurationStore.getInstance().getConfiguration() 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/ambra/libs/conf-helper/src/main/java/org/topazproject/ambra/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.topazproject.ambra.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.topazproject.ambra.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 permit-creator.xml