Configuration Module

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.

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();
}

A possible implementation is the DefaultRenderingConfiguration class:

@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

OR

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

Search this space

 

Most popular tags

Failed to execute the [groovy] macro
  1. access rights
  2. activity stream
  3. annotation
  4. attachment
  5. comment
  6. Document Tree Macro
  7. export
  8. Extension Manager
  9. Flamingo skin
  10. global user
  11. Groovy event listener
  12. group
  13. nested page
  14. search
  15. skin
  16. syntax
  17. user
  18. user profile
  19. velocity macros
  20. wiki
  21. wysiwyg
  22. XWiki Applications
  23. xwikiattachment_archive table
  24. xwikiattachment table
  25. xwikiattrecyclebin table
  26. xwikiproperties table

[Display all tags from this space]