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. Activity Stream Plugin
  4. annotation
  5. attachment
  6. CKEditor
  7. comment
  8. Document Tree Macro
  9. edit
  10. Error Message macro
  11. export
  12. Extension Manager
  13. Extension module
  14. Flamingo skin
  15. global group
  16. global user
  17. Groovy event listener
  18. Groovy module
  19. group
  20. import
  21. Info macro
  22. java macros
  23. MySQL
  24. nested page
  25. network
  26. Office Importer
  27. page
  28. RSS
  29. search
  30. skin
  31. SOLR
  32. statistics
  33. Success Message macro
  34. syntax
  35. user
  36. user profile
  37. velocity macros
  38. Warning macro
  39. wiki
  40. Wiki Application
  41. wiki macro
  42. wysiwyg
  43. XWiki Applications
  44. xwikiattachment_archive table
  45. xwikiattachment_content table
  46. xwikiattachment table
  47. xwikiattrecyclebin table
  48. xwikiproperties table

[Display all tags from this space]

External Links