Configuration Module
 | Provides the infrastructure for components needing configuration data |
| Type | components |
| Category | |
| Developed by | Unknown |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
Table of contents
Description
The way to use this module is simple:
- Each module creates an interface named <optional prefix><module name>Configuration (e.g. RenderingConfiguration, IconTransformationConfiguration, etc)
- Each module creates an implementation of that interface, named Default<optional prefix><module name>Configuration (e.g. DefaultRenderingConfiguration)
- The interface implementation uses one of the ConfigurationSource components provided by this Configuration module. These ConfigurationSource implementations are bound to sources where to get configuration data from: properties file, xwiki documents, etc.
- Each module needs to respect the naming conventions for configuration properties.
Technically we use Apache Commons Configuration under the hood to perform the heavy lifting. This means we have the possibility to create lots of different Configuration Sources, to get the configuration data from JNDI, Database, etc. We also benefit from Commons Configuration's ability to define Lists and Maps in properties file and the support of variable interpolation.
Example
Interface:
public interface RenderingConfiguration
{
String getLinkLabelFormat();
Properties getMacroCategories();
Properties getInterWikiDefinitions();
Implementation:
public class DefaultRenderingConfiguration implements RenderingConfiguration
{
/**
* Prefix for configuration keys for the Rendering module.
*/
private static final String PREFIX = "rendering.";
/**
* @see #getLinkLabelFormat()
*/
private static final String DEFAULT_LINK_LABEL_FORMAT = "%p";
/**
* Defines from where to read the rendering configuration data.
*/
@Requirement
private ConfigurationSource configuration;
/**
* {@inheritDoc}
*
* @see XWikiRenderingConfiguration#getLinkLabelFormat()
*/
public String getLinkLabelFormat()
{
return this.configuration.getProperty(PREFIX + "linkLabelFormat", DEFAULT_LINK_LABEL_FORMAT);
}
/**
* {@inheritDoc}
*
* @see XWikiRenderingConfiguration#getMacroCategories()
*/
public Properties getMacroCategories()
{
return this.configuration.getProperty(PREFIX + "macroCategories", Properties.class);
}
/**
* {@inheritDoc}
*
* @see org.xwiki.rendering.internal.configuration.XWikiRenderingConfiguration#getInterWikiDefinitions()
*/
public Properties getInterWikiDefinitions()
{
return this.configuration.getProperty(PREFIX + "interWikiDefinitions", Properties.class);
}
}
Available Configuration Sources
"xwikiproperties"
You get access to this configuration source by using:
private ConfigurationSource configuration;
It reads configuration properties from the xwiki.properties file located in your webapp's WEB-INF directory.
"wiki"
You get access to this configuration source by using:
private ConfigurationSource configuration;
It reads configuration properties from the running XWiki instance, by reading properties from the XWiki.XWikiPreferences object in the XWiki.XWikiPreferences document.
"space"
You get access to this configuration source by using:
private ConfigurationSource configuration;
It reads configuration properties from the running XWiki instance, by reading properties from the XWiki.XWikiPreferences object in the current space's WebPreferences document.
"user"
You get access to this configuration source by using:
private ConfigurationSource configuration;
"default"
You get access to this configuration source by using:
private ConfigurationSource configuration;
Configuration properties are first looked for in the "space" source, if not found then in the "wiki" source and if not found in the "xwikiproperties" source. This is the recommended configuration source for most usages since it allows to defined configuration properties in the xwiki.propertieds file and to override them in the running wiki (globally or per space).
Properties Naming Rules
- Remove the org.xwiki or com.xpn.xwiki part before the module's package name (e.g. rendering for org.xwiki.rendering)
- Use <module>.<propertyName> (e.g. rendering.linkLabelFormat)
- For submodules use <module>.<sunmodule>.<propertyName> (e.g. rendering.macro.velocity.filter)
- Use camelcase for the property name itself (.e.g linkLabelFormat)
List and Map definition in properties files
To define a List in a property file use one of the following methods:
propertyName = item2
propertyName = item3
In the code you'll get access to the List by doing:
To define a Map in a property file use the following:
propertyName = item2 = value2
propertyName = item3 = value3
In the code you'll get access to the Map by doing:
Variable interpolation in properties files
Example:
property2 = ${property1}
