Skip to Content

Performances development best practices

Version 5.1 by Thomas Mortagne on 2025/05/16
Warning: For security reasons, the document is displayed in restricted mode as it is not the current version. There may be differences and errors due to this.
Contents

Database

Index

Filtering and ordering on a non indexed field (for example, searching for something in the content of a document) will cause very important performance problems as soon as that table starts to contain a lot of entries. Not only for the query you are trying to execute but also for other queries running in the database server.

You can also have a similar problem when combining several indexed field in the same WHERE clause, as, in theory, for this to be fast, you would need to have an index combining those fields. Unfortunately, very often, it's not possible in XWiki to do that (at least with MySQL/MariaDB) because most String columns already have the maximum size accepted for an index, and combining them would go beyond that limit.

The possible alternatives are generally:

  • Use the Solr search core instead.
  • Do post filtering/ordering on your side instead of the database (but this can cause problems when you need pagination)

Components

Wiki components are slow

Wiki components are discouraged because they are much slower than the alternatives (beside various other problems).

If you really need to implement your component in a wiki page, you should take a look at Script Component (which also makes implementing, and especially registering, components in a wiki page a lot easier). What will be produced in the end is technically exactly the same thing as what you get with a component implemented in Java.

Rendering

When implementing a macro

When you implement your own macro, there are various performance related things that you should be aware of.

Wiki macros are much slower than Java macros

So you should try as much as possible to implement Java macros (it's also much easier to write automated tests for Java macros). It's not always very practical to write complex UI in Java, but you can easily execute a template from your Java code.

Like with any other component, you can implement a Java macro through Script Component if you absolutely need your macro to be implemented in a wiki page. What will be produced in the end is technically exactly the same thing as what you get with a macro implemented in Java.

Macro preparation

Information

  Currently, not supported in Wiki macros.

There are two steps in the execution of a macro:

  • the preparation
  • the actual execution

During the preparation step, you get a chance to do everything that does not rely on any contextual information and store the result in the MacroBlock (as attribute). It can improve execution time greatly because the MacroBlock is generally part of cached data, so the preparation will be executed only once for potentially many executions.

Isolated execution

XWiki 17.3.0+

If your macro does not modify the XDOM around it (which is the case most of the time), it's highly recommended to indicate it:

HTML Macro

The cleaning part of the HTML macro can be expensive, so using clean="false" could have a significant impact on the performance if a lot of them are used.

Preparation

Preparing Blocks

Similarly to what is explained for macros, it's a good idea to parse and "prepare" any wiki content you are planning to execute several times. It will generally considerably reduce the execution time.

You can do that by calling Transformation#prepare(Block block) in Java. If you don't know which Transformation to apply, apply at least the macro one:

  @Inject
 @Named("macro")
 private Translation macroTransformation;

 private XDOM cachedXDOM;

 void cacheContent(String wikiContent)
 {
   this.cachedXDOM = parse(wikiContent);
   this.macroTransformation.prepare(cachedBlock);
 }

 ...

Compiling Velocity

If you have the possibility to cache a Velocity script, it's generally a good idea to pre-compile it. In the case of Velocity it means parsing the String into an AST, which can be an expensive step.

  @Inject
 private VelocityManager velocityManager;

 private VelocityTemplate cachedVelocity;

 void cacheContent(String velocityScript)
 {
   this.cachedVelocity = this.velocityManager.compile(nameAssociatedtoTheScript, velocityScript)
 }

 void evaludate(Writer writer)
 {
   ...
   this.velocityManager.getVelocityEngine().evaluate(velocityContext, writer, namespace, this.cachedVelocity);
 }

 ...

This is, for example, what the Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [xwiki:Documentation.DevGuide.Performances.WebHome]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
 is doing as part of it's macro preparation step.

UI extensions

Wiki-based UI extensions are slower than Java-based ones

What is true for generic wiki components and wiki macros is also true for UI extensions.

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected