URL Architecture

Last modified by Simon Urli on 2023/12/07

This is how URLs are handled when entering an XWiki instance:

Specifically:

  • When parsing an incoming URL, the Routing Filter will use a default Resource Type Resolver (ResourceTypeResolver) component to extract the Resource Type (ResourceType) from the URL (the Resource Type is the type of URL pointed to, e.g. an Entity if the URL is pointing to a Document for example, a WebJar URL, a Skin URL, a REST URL, etc). In turn, the default Resource Type Resolver will read the XWiki configuration to see what URL Scheme is configured (through the url.format configuration parameter) and will then locate a ResourceTypeResolver component with a hint corresponding to the URL Scheme. It'll use it to extract the Resource Type.
  • The Resource Reference Handler Servlet will use a default Resource Reference Resolver (ResourceReferenceResolver) component to parse the passed URL into a ResourceReference object that can then be given to a ResourceReferenceHandler to perform an action. In turn the default Resource Reference Resolver will read the XWiki configuration to see what URL Scheme is configured (through the url.format configuration parameter) and will then locate a ResourceReferenceResolver component with a hint corresponding to the URL Scheme. It'll use it to extract the Resource Reference. 

For more details see the Resource API and the URL API reference documentation.

Standard URL Scheme

This is the default URL format used by XWiki. See Standard URL Scheme.

Customizing URLs

There are several solutions to customize XWiki URLs:

  • You can tune them to some degree by modifying XWiki's configuration. The various options are described in the Short URL documentation.
  • You can rewrite both incoming URLs but also outbound URLs using a Rewrite Filter. An example is also provided in the Short URL documentation.
  • You can implement a new URL Scheme. See the URL API.
  • You can simply register new Resource Types or new Entity Actions. See the Resource API.

Note that using Tuckey's Rewrite Filter is very powerful as it also allows using dynamic rules written in Java by using the <class-rule> feature. However, dynamic outbound rules are not yet possible.

Here's an example of writing a custom class-rule.

Legacy Actions Servlet Architecture

As shown above, when there's no Resource Reference Handler registered to handle a Resource Type, the rest of web.xml is processed and if the URL type is bin or wiki, the Servlet in charge of the legacy actions is then called and the following happens:

For example for the http://www.xwiki.org/xwiki/bin/view/Main/WebHome URL for the standard URL scheme, the following happens:

  • XWiki 13.0+ The URL path contains /view/ and thus the ViewAction class is executed (because the role hint of the ViewAction component is view) and called by the Legacy Action Servlet, itself configured in web.xml

    XWiki <13.0 The mapping between the URL and the Action class to execute is defined in struts-config.xml, and the Struts Action is configured in web.xml.

  • The wiki is the main wiki in this example (since the server name starts by www). See Accessing a wiki for more details on how wikis are accessed from URLs.
  • ViewAction specifies that view.vm will be rendered using Velocity
  • The space asked is Main and the document's name is WebHome

Redirections

  • A redirection is automatically applied if an object of type XWiki.RedirectClass is found at the requested location. In this case the user is redirected to the location stored in the location field of the XWiki.RedirectClass.
  • Redirection can also be defined programmatically, see How to add a redirect?

XWiki 14.0+ New redirection logic can be provided by implementing the RedirectionFilter role. The redirection filters are evaluated in their priority order and the first to make a redirection is applied. If no redirection are found, the execution logic of the requested location is returned.
 

Be aware that the redirection performed with a XWiki.RedirectClass concerns all actions supporting redirect, including download. This means, for example, that a URL to download an attachment will look for the attachment in the target of the redirect. If you want to have a more custom way of handling the actions to redirect in an extension, you should create your own custom Redirect xclass, and your own RedirectionFilter component with the behaviour you want.

Tags:
   

Get Connected