The Configuration Module provides the infrastructure for Components that require configuration data. XWiki uses the Apache Commons Configuration for creating configuration sources and retrieving the configuration data. The available configuration sources are listed below.
The source code of the Configuration Module is available on GitHub at:
Usage
New modules should be created following 2 main rules:
- Each module creates an interface for which the naming convention is: <optional prefix><module name>Configuration. Also, modules must respect the Naming Conventions for Configuration Properties.
- Each module creates an implementation of that interface which respects the naming convention Default<optional prefix><module name>Configuration and uses one of the available Configuration Sources.
Configuration Sources
xwikiproperties
The xwikiproperties configuration source reads configuration properties from the WEB-INF/xwiki.properties file and can be accessed using the below code:
@Requirement("xwikiproperties")
private ConfigurationSource configuration;
The source code of the "XWikiPropertiesConfigurationSource" class is available on GitHub.
wiki
The wiki configuration source reads configuration properties from the "XWiki.XWikiPreferences" object attached to the "XWiki.XWikiPreferences" wiki page of the running XWiki Enterprise instance. It can be accessed using the code:
@Requirement("wiki")
private ConfigurationSource configuration;
The source code of the "WikiPreferencesConfigurationSource" class is available on GitHub.
space
The space configuration source reads configuration from the "XWiki.XWikiPreferences" object attached to the "WebPreferences" page of the current wiki space. It can be accessed using the code:
@Requirement("space")
private ConfigurationSource configuration;
The source code of the "SpacePreferencesConfigurationSource" class is available on GitHub.
user
The user configuration source exists but it is not yet implemented. The source code of the "UserPreferencesConfigurationSource" class is available on GitHub.
default
The configuration properties priority is:
- the space source
- the wiki source
- the xwikiproperties source
The source code of the "DefaultConfigurationSource" class is available on GitHub.
Naming Conventions for Configuration Properties
1. The org.xwiki or com.xpn.xwiki part from the module's package name should be removed. E.g. rendering instead of org.xwiki.rendering
2. For module properties the naming convention is: [module].[propertyName]. E.g. rendering.linkLabelFormat.
3. For sub-module properties, the naming convention is: [module].[sub-module].[propertyName]. E.g. rendering.macro.velocity.filter.
4. For the property name, it is recommended to use camel-case.
Example
As explained in the above paragraph, each module creates an interface and an implementation of that interface. One example is the RenderingConfiguration interface:
@ComponentRole
public interface RenderingConfiguration
{
String getLinkLabelFormat();
List<String> getTransformationNames();
Properties getInterWikiDefinitions();
}
@Component
@Singleton
public class DefaultRenderingConfiguration implements RenderingConfiguration, Initializable
{
/**
* The logger to log.
*/
@Inject
private Logger logger;
/**
* Used to look up Transformations at runtime.
*/
@Inject
private ComponentManager componentManager;
/**
* Holds the names of transformations to apply (in any order, the Transformation Manager will execute them in the
* proper order).
*/
private List<String> transformationNames = new ArrayList<String>();
/**
* @see #getLinkLabelFormat()
*/
private String linkLabelFormat = "%p";
/**
* @see #getInterWikiDefinitions()
*/
private Properties interWikiDefinitions = new Properties();
@Override
public void initialize() throws InitializationException
{
// Find the names of all registered Transformations.
List<ComponentDescriptor<Transformation>> descriptors =
this.componentManager.getComponentDescriptorList((Type) Transformation.class);
for (ComponentDescriptor<Transformation> descriptor : descriptors) {
this.transformationNames.add(descriptor.getRoleHint());
}
}
@Override
public String getLinkLabelFormat()
{
return this.linkLabelFormat;
}
/**
* @param linkLabelFormat the format used to decide how to display links that have no label
*/
public void setLinkLabelFormat(String linkLabelFormat)
{
// This method is useful for those using the XWiki Rendering in standalone mode since it allows the rendering
// to work even without a configuration store.
this.linkLabelFormat = linkLabelFormat;
}
@Override
public Properties getInterWikiDefinitions()
{
return this.interWikiDefinitions;
}
/**
* @param interWikiAlias see {@link org.xwiki.rendering.listener.reference.InterWikiResourceReference}
* @param interWikiURL see {@link org.xwiki.rendering.listener.reference.InterWikiResourceReference}
*/
public void addInterWikiDefinition(String interWikiAlias, String interWikiURL)
{
// This method is useful for those using the XWiki Rendering in standalone mode since it allows the rendering
// to work even without a configuration store.
this.interWikiDefinitions.setProperty(interWikiAlias, interWikiURL);
}
/**
* @param transformationNames the explicit list of transformation names to execute (overrides the default list)
*/
public void setTransformationNames(List<String> transformationNames)
{
this.transformationNames = transformationNames;
}
@Override
public List<String> getTransformationNames()
{
return this.transformationNames;
}
}
Define a List in a Property File
To define a List in a property file you can either write
propertyName = item1
propertyName = item2
propertyName = item3
propertyName = item1, item2, item3
In order to access the List, use: List values = this.configuration.getProperty("propertyName", List.class);
Define a Map in a Property File
To define a Map in property file you can use the below code:
propertyName = item1 = value1
propertyName = item2 = value2
propertyName = item3 = value3
To access the Map, use: Properties values = this.configuration.getProperty("propertyName", Properties.class);
Variable Interpolation
Supposing you need to define the path for 2 folders, "extensionPath" and "indexPath", the values of the 2 variables would be:
extensionPath=/usr/local/xwiki/extension
indexPath=/usr/local/xwiki/extension/index
The "/usr/local/xwiki/extension" part is common for the 2 variables, so you could write:
extensionPath=/usr/local/xwiki/extension
indexPatch=${extensionPath}/index
Related Pages
Trying to decide between Cloud and On Premise? See the comparison on the XWiki Help Center.