Extensions Wiki » Extensions » Configuration Module

Configuration Module

Last modified by Vincent Massol on 2013/03/11 09:38
cogProvides the infrastructure for components needing configuration data
TypeJAR
Developed by

XWiki Development Team

LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Enterprise, XWiki Enterprise Manager

Description

If you're looking on how to configure XWiki check the Configuration page in the Platform Admin Guide.

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:

@ComponentRole
public interface RenderingConfiguration
{
    String getLinkLabelFormat();
    Properties getMacroCategories();
    Properties getInterWikiDefinitions();

Implementation:

@Component
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:

@Requirement("xwikiproperties")
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:

@Requirement("wiki")
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:

@Requirement("space")
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:

@Requirement("user")
private ConfigurationSource configuration;
This configuration source exists but is not implemented yet. If you use it, it won't have any effect.

"default"

You get access to this configuration source by using:

@Requirement
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 = item1
propertyName = item2
propertyName = item3
propertyName = item1, item2, item3

In the code you'll get access to the List by doing:

List values = this.configuration.getProperty("propertyName", List.class);

To define a Map in a property file use the following:

propertyName = item1 = value1
propertyName = item2 = value2
propertyName = item3 = value3

In the code you'll get access to the Map by doing:

Properties values = this.configuration.getProperty("propertyName", Properties.class);

Variable interpolation in properties files

Example:

property1 = value1
property2 = ${property1}
Tags: development
Created by Vincent Massol on 2010/10/26 10:05

Download XWiki

Get Connected