Variability is an important aspect of the architectural design of XWiki¹. It is highly configurable, supports a lot of different database systems and servlet containers, and can be extended with more than 600 extensions that add features to the application. We will first discuss the variability of XWiki at installation and of the run-time functionality. We will continue talking about the ways variability can be managed from a stakeholders perspective and finally dive a bit deeper into one technical detail of XWiki to discuss the way variability is implemented in XWiki, concluding with some design choices.

Variability at installation

When installing XWiki, a choice between three different versions is given: the current version under development, the latest stable release, and the long-term support version ². While the first two versions contain the latest updates and therefore more features, the long-term support version is promised to be more stable, and therefore less likely to display unexpected behaviour.

All three of these versions can be downloaded in multiple variants with different configurations in place. First, a choice can be made between two different demo versions and four different general product installations³. While the general product installations need the configuration of a database, a servlet container and a choice of a flavour package, the demo version has these (partially) already installed. This allows the demo versions to be used just out of the box, while the general product installations need some more configurations.

When choosing the general product installation, four different installation methods can be used: as WAR package, as Debian/Ubuntu package as docker image and as XIP package³. Which one of the four to use, depends on the operating system, the preferences of the developer and whether internet accessibility is available. The compatible database-systems and servlet containers may also differ per installation. A more detailed description of the supported features and its incompatibilities can be found below.

Variability of run-time functionality

Since the different usages of XWiki are varied, there are also different ways you can set up XWiki to include the functionalities that you need. These different functionalities are implemented as add-ons which are called “extensions”. We already explained the concept of the extensions in our second essay of this series, but here we will take another look at it.

Extensions can be useful when you want to add functionalities to XWiki that are specific to a use case. A newly installed version of XWiki only has the base features ⁴ available, which are basically the minimum expected functionalities of a wiki, like page editing, content organization and navigation. When starting XWiki for the first time there is an option to add an extension called the XWiki Standard flavor. This extension is developed by the XWiki Development Team and consists of a list of extensions that are useful for a generic use case of XWiki, including the help center, icon themes and a search functionality. Other extensions can be added to XWiki during run-time using the Extension Manager.

Incompatibilities

To make it easy for users to work with extensions, the Extension Manager handles the installation and the dependencies of extensions. When an extension requires another extension to be installed for it to work, these dependencies are identified, as seen in the image below, and are downloaded automatically.

In some cases, however, extensions require a specific version of XWiki in order to work. When the version of XWiki does not meet these requirements, this extension is incompatible and cannot be installed. These incompatibilities are usually not experienced by the user; only when users allow incompatible extensions in their search results, can these extensions show up. For these extensions, it is also clearly shown that they are incompatible, as can be seen in the image below.

Feature model

Since there are more than 600 available extensions for XWiki, making a feature model for all possible functionalities constructed with these extensions would simply be impossible. We therefore decided to look at the base functionalities that are included in every installation of XWiki: the base features ⁴. The feature model of these functionalities can be seen below.

In this model all the base features of XWiki can be found along with their subfeatures. Since these functionalities are included in every XWiki project, almost all functionalities in this model are mandatory. The two functionalities that are optional are those that can be added with an extension. The skin extension, however, has been made mandatory, since one is required for XWiki. A user can choose their own skin extension or keep the default.

Variability management

For any project with a large amount of variability, it is important that significantly involved stakeholders understand the variability and are able to work with it. Because of this reason, the variability should be managed and documented properly. Therefore, we explain how variability is managed in this section. First, we will look at the way documentation is used to manage variability for stakeholders. After that, we dive into several mechanisms, in place for variability management during development.

Variability management for users and developers

It is important that there exists a proper understanding of the variable aspects of the XWiki project within the community. Therefore, there should be enough documentation available related to variability management, both for installation and run-time variability, and for development.

Variability at installation

As was stated earlier in this essay, variability is partly achieved by providing the possibility for users to use several databases and several types of servlet containers. For the databases, there is much documentation available, ranging from a list of usable databases, to database specific documentation. For the servlet containers, similar documentation is available: a list of supported containers and different installation instructions.

Variability at run-time

To assist the use of different extensions, extension documentation exists. This documentation can be seen as a large knowledge base of every publicly available XWiki extension and is meant predominantly for XWiki users that want to integrate extensions into their XWiki instance. The documentation therefore contains information on a variety of things, such as a description, dependencies, prerequisites, and installation instructions. These pieces of information can significantly aid in extensions management.

Also, the extension documentation assists users in searching for extensions, by providing the ability to filter for extensions based on several criteria.

Variability for development

While there is significantly less documentation available concerning the variability for developers, there is a general architecture documentation page, introducing developers with the way variability is used in XWiki. Also, on the database side, there is information available on the database schema and data model of XWiki.

Variability management mechanisms

To ease the usage and management of variability in XWiki, several tools exist. These are tools intended for both XWiki users and XWiki developers, and tools intended for both installation and run-time variability.

Variability at installation

To configure the mapping between the application and database, XWiki uses Hibernate. Hibernate is a high-performance Object/Relational persistence and query service⁵. This allows XWiki users to make XWiki work with a different database and database scheme, by simply changing a Hibernate configuration file. How Hibernate is used exactly in XWiki, is discussed in the last section.

Variability at run-time

As mentioned before in this blog, the extension manager is an application that serves as a UI to install, remove, and upgrade extensions.

The manager has several features supporting extensions management. These are features such as search, conflict resolution and installation management. The extension manager is built on top of the extension module, which was explained in detail in one of our previous blog posts.

Furthermore, there exists a feature called the Distribution Wizard This allows XWiki users to select a Flavor for their XWiki instance and can also be used to easily upgrade XWiki instances to work with newer extensions.

Variability for development

For developers, XWiki is constantly working on mechanisms to improve variability management, especially for software testing. For a long time, there was no strategy for automated testing on different environments. Instead, automated tests were performed on a single environment (a combination of Firefox, Jetty and HSQLDB), and other environment configurations were manually tested ⁶. However, to be able to perform automated tests in any environment configuration, several options have been and are being experimented with. While all of these options are interesting, we focus on one of them: TestContainers.

TestContainers is a library that allows JUnit testing to be done in lightweight and configurable containers. Concretely, this means that different types of containers, such as database and servlet containers, can be created directly from unit tests, such that these different environments can be tested automatically.

An overview of this can be seen in the figure below.

The TestContainer strategy is one of the strategies that are currently used by XWiki. The other strategies that XWiki experimented with can be found here.

Variability implementation choices

We will now have a more detailed look at the implementation of variability in XWiki. To do this, we will use the example of the way a database can be implemented and modified by developers and users. Using this example, we will talk about XWiki’s general design choices, scalability and potential future developments.

Variability in databases

As mentioned before, the choice of installation method is intertwined with database design decisions. Some installation methods include a portable (HSQLDB) database (a standalone distribution for testing XWiki), or work in the cloud. When using an official XWiki Docker image or .deb/.war package (usable for production), the user has a choice what database to link with XWiki. XWiki “supports” most commonly used databases, meaning they include these databases in tests and make their best effort on fixing JIRA issues created for these databases ⁷. The whole XWiki package is downloaded completely, and database configurations are set during setup, known as a load-time binding variability. All choices are saved in configuration files, whereafter the property of database location is available in the XWiki context. To access the database correctly depending on the chosen product, XWiki uses a Hibernate database driver. Ideally this means developers of XWiki should not have to take care of Database specificities, however, Hibernate does not support all settings used (Hibernate does not support setting Catalogues on some databases). Calls for the chosen database can be found in large and smaller IF statements where Hibernate’s Dialect⁸ does not offer all translations to access the database properly. An example of this can be found in HibernateStore.java:

        // In various places we need the canonical database name (which is upper case for HSQLDB, Oracle and H2) because
        // the translation is not properly done by the Dialect
        if (DatabaseProduct.HSQLDB == product || DatabaseProduct.ORACLE == product || DatabaseProduct.H2 == product) {
            database = StringUtils.upperCase(database);
        }

Some more variability on the database topic is Custom Mapping. The database schema is predefined and can be found here. Although is not recommended to modify this schema, an XWiki Class can make use of a Custom Mapping to map it to its own database table. Custom mappings can improve performances, or can be used to share external data with XWiki. In this case a Hibernate mapping file should be defined, be referenced in the main Hibernate configuration file, and the XWiki class should be set as containing a custom mapping.

Design choices

XWiki’s architecture is specifically designed to be extended; the development of new features is encouraged by the XWiki Extensions community. Thanks to this open and free development strategy, new features in the run-time binding/extensions category are constantly being published. These upgrades do not require a complete reinstall of the XWiki product, but can be updated from a browser.

The choice to use external services for variable features, like the database Hibernate driver, come with both downsides and upsides. Benefits include simplifying development (no need for duplicate code), improved performance (when you assume tools offering a specific task are optimised for this task), and increased functionality from updates and improvements of this tool. A drawback of using external services is that you are either limited to the given features of the tool, or that you still have to write duplicate code as shown in the code-example above.

The current roadmap of XWiki is not focused on extending variable features in any general goals. On the XWiki forum, more detailed roadmaps for each monthly update are discussed, where it can be seen that some variable features are being extended or refactored. While adding features is not stated as a general goal of the main developers of XWiki, the scalable architecture and the extension community allow for great variability of the XWiki project.