XWiki Standard 9.8.1 Documentation » Programming Overview » XWiki Platform Modules Overview » Link Checker Module and Link Checker Transformation

Link Checker Module and Link Checker Transformation

The Link Checker Module provides the API to access states of external links found in the wiki and it is based on the Link Checker Transformation. The module is used by the Link Checker Application and it basically performs a link state cache refresh, i.e. clearing the cache of external links found in a saved page. 

The Link Checker Transformation

The Link Checker Transformation is a rendering transformation that checks the validity of external links found in the wiki. The result is stored in memory and can be later accessed through a component or a script service

The transformation works as follows:

  • The Link Checker Transformation creates a LinkCheckerThread which has a low priority.
  • The external links found in wiki pages are placed in a queue so they won't affect the rendering process. In order for links to be placed there, the queue must contain less than 10 items (which is the default value).  
  • The Link Checker thread checks whether the queue contains links that need to be verified. If so, links are called one by one and the response code of the HTTP request is stored in the memory.

    Links from pages that are in the exclude list won't be checked. 

    A list of document references that are excluded from link checking can be specified as a regular expression in the "WEB-INF/xwiki.properties" configuration file: # rendering.transformation.linkchecker.excludedReferencePatterns = .*:XWiki\.ExternalLinksJSON

  • The Link Checker thread rechecks a given link after a given timeout. The default timeout value is 1 hour and it can be configured from the "WEB-INF/xwiki.properties" file:
    #-# [Since 3.3M2]
    #-# Defines the time (in ms) after which an external link should be checked again for validity.
    #-# the default configuration is:
    # rendering.transformation.linkchecker.timeout = 3600000
  • When an external link is checked and a response code less than 200 or greater than 299 is returned, then an event of type InvalidURLEvent is sent and the passed Event data is a Map containing the following key/values:
    • url: the link reference
    • source: it can be either the reference to the source where the link was found or "default" if no source reference is found
    • state: a LinkState containing the response code and the last checked time.

Enable the LinkChecker Transformation

The LinkChecker transformation is disabled by default. In order to enable it, edit the "WEB-INF/xwiki.properties" configuration file, uncomment the rendering.transformations parameter and add the "linkchecker" value as follows: rendering.transformations = macro, icon, linkchecker. A server restart is required in order for the change to apply.

Access Link States from a Component

Add the following dependency to the "pom.xml" file of your project 


then use the getLinkStates() method:

private LinkStateManager linkStateManager;
public void myMethod()
    Map<String, Map<String, LinkState>> linkStates = this.linkStateManager.getLinkStates();
import groovy.util.logging.*
import org.xwiki.observation.*
import org.xwiki.observation.event.*
import org.xwiki.rendering.transformation.linkchecker.*
import com.xpn.xwiki.web.*
import com.xpn.xwiki.*

class MyInvalidLinkListener implements EventListener
    def xwiki
    def context

   MyInvalidLinkListener(xwiki, context)
       this.xwiki = xwiki
       this.context = context

   String getName()
      return "myInvalidLinkListener"

   List<Event> getEvents()
      return Arrays.asList(new InvalidURLEvent())

  void onEvent(Event event, Object eventSource, Object data)
        def url = eventSource.get("url")
        def source = eventSource.get("source")
        def state = eventSource.get("state")

       log.info("Error for {url} in ${source} - Response code: ${state.getResponseCode()} - Checked: ${String.format('%tF %<tT', state.getLastCheckedTime())}")

  // Register against the Observation Manager
  def observation = Utils.getComponent(ObservationManager.class)
   def listener = new MyLinkListener(xwiki, xcontext)


Related Pages

Trying to decide between Cloud and On Premise? See the comparison on the XWiki Help Center.

Search this space