Wiki source code of Wiki URL Resolution
Last modified by Eleni Cojocariu on 2026/10/20 19:02
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
2.1 | 1 | Every request that reaches a [[wiki farm>>doc:documentation.xs.admin.wikis.WebHome]] names the wiki it is for, in the path of the URL or in the host name. This page states which wiki XWiki serves for a given URL, and the properties that decide the form XWiki writes. |
| 2 | |||
| 3 | == The Two URL Forms == | ||
| 4 | |||
| 5 | A path-based URL carries the wiki in a path segment: | ||
| 6 | |||
| 7 | {{code language="none"}} | ||
| 8 | http://myfarm.example.org/xwiki/wiki/mywiki/view/Space/Page | ||
| 9 | {{/code}} | ||
| 10 | |||
| 11 | A domain-based URL carries it in the host name: | ||
| 12 | |||
| 13 | {{code language="none"}} | ||
| 14 | http://mywiki.example.org/xwiki/bin/view/Space/Page | ||
| 15 | {{/code}} | ||
| 16 | |||
| 17 | The segment that follows the context path tells the two apart: ##wiki## means the wiki is the segment after it, ##bin## means the wiki is the host name. A URL with no ##wiki## segment is therefore read as a domain-based one. Everything after the wiki follows the [[standard URL format>>xwiki:Documentation.DevGuide.Architecture.URL Architecture.Standard URL Format.WebHome]], which the farm does not change. | ||
| 18 | |||
| 19 | == Configuration Properties == | ||
| 20 | |||
| 21 | All four are read from ##WEB-INF/xwiki.properties##. The ##WEB-INF/xwiki.cfg## twins are the older names for the same settings, and they are still read, so the two files have to agree. | ||
| 22 | |||
| 23 | |=Property|=Default|=##xwiki.cfg## twin|=Sets | ||
| 24 | |##url.standard.multiwiki.isPathBased##|##true##|##xwiki.virtual.usepath##, ##1##|Which of the two forms XWiki writes | ||
| 25 | |##url.standard.multiwiki.wikiPathPrefix##|##wiki##|##xwiki.virtual.usepath.servletpath##|The segment that marks a path-based URL | ||
| 26 | |##url.standard.multiwiki.notFoundBehavior##|##redirect_to_main_wiki##|##xwiki.virtual.failOnWikiDoesNotExist##, ##0##|What is served when no wiki matches | ||
| |
5.1 | 27 | |##url.standard.entityPathPrefix##|##bin##|##xwiki.defaultservletpath##, ##bin/##|The segment a domain-based URL carries where a path-based one carries the wiki |
| |
2.1 | 28 | |
| 29 | == Which Form XWiki Writes == | ||
| 30 | |||
| |
5.1 | 31 | Setting ##isPathBased## alone is not enough. The URL module falls back to the ##xwiki.cfg## value only when the property is absent, but the factory that builds links and the filter that rewrites form submissions read ##xwiki.virtual.usepath## alone, so a disagreement leaves part of the instance writing the other form. [[Switch to Domain-Based URLs>>doc:documentation.xs.admin.wikis.switch-domain-based-urls.WebHome]] sets both. |
| |
2.1 | 32 | |
| 33 | == The Wiki Path Segment == | ||
| 34 | |||
| 35 | Renaming ##wikiPathPrefix## also moves where the servlet container has to route the segment, so follow [[Change the Wiki Path Segment>>doc:documentation.xs.admin.wikis.change-path-segment.WebHome]] rather than editing the property alone. | ||
| 36 | |||
| 37 | == Wiki Descriptors == | ||
| 38 | |||
| 39 | A wiki descriptor is a page of the main wiki, in the ##XWiki## space, holding an ##XWiki.XWikiServerClass## object. Its page name is ##XWikiServer## followed by the wiki id, and the id XWiki reads back from that name is the suffix in lower case. The object's ##server## field holds an alias that a URL may use, and a descriptor page may hold several such objects, each one adding another alias for the same wiki. | ||
| 40 | |||
| 41 | The first of those objects is not interchangeable with the others: its ##server## field is the wiki's default alias, the one XWiki writes into the URLs it generates for that wiki, in either form. The rest are read when resolving a URL and never when writing one. | ||
| 42 | |||
| 43 | The id and the alias are independent, which is what makes the rules below readable: the page ##XWiki.XWikiServerTest## whose ##server## field is ##somewiki## describes the wiki whose id is ##test##, and the path-based URL that reaches it is ##/xwiki/wiki/somewiki/view/Space/Page##. | ||
| 44 | |||
| 45 | == Resolution Order == | ||
| 46 | |||
| 47 | XWiki resolves the wiki before it looks at anything else in the request, and the resolved id is always lower-cased: | ||
| 48 | |||
| 49 | {{plantuml}} | ||
| 50 | @startuml | ||
| 51 | !theme bluegray | ||
| 52 | skinparam defaultTextAlignment center | ||
| 53 | |||
| 54 | start | ||
| 55 | if (First path segment after the context path) then (wiki) | ||
| 56 | :The alias is the next path segment; | ||
| 57 | if (A descriptor whose server field is the alias) then (found) | ||
| 58 | :Serve that descriptor's wiki; | ||
| 59 | stop | ||
| 60 | endif | ||
| 61 | :Candidate wiki id: the alias; | ||
| 62 | else (bin) | ||
| 63 | :The alias is the host name; | ||
| 64 | if (A descriptor whose server field is the alias) then (found) | ||
| 65 | :Serve that descriptor's wiki; | ||
| 66 | stop | ||
| 67 | endif | ||
| 68 | if (The host is localhost or an IP address,\nor its first label is www) then (yes) | ||
| 69 | :Serve the main wiki; | ||
| 70 | stop | ||
| 71 | endif | ||
| 72 | :Candidate wiki id: the host\nup to the first dot; | ||
| 73 | endif | ||
| 74 | |||
| 75 | if (A descriptor page named after the candidate id) then (found) | ||
| 76 | :Serve that wiki; | ||
| 77 | stop | ||
| 78 | endif | ||
| 79 | |||
| 80 | if (url.standard.multiwiki.notFoundBehavior) then (redirect_to_main_wiki) | ||
| 81 | :Serve the main wiki; | ||
| 82 | else (display_error) | ||
| 83 | :Answer 404,\nthe wiki does not exist; | ||
| 84 | endif | ||
| 85 | stop | ||
| 86 | @enduml | ||
| 87 | {{/plantuml}} | ||
| 88 | |||
| 89 | == When the Wiki Does Not Exist == | ||
| 90 | |||
| 91 | ##notFoundBehavior## decides that last branch. ##redirect_to_main_wiki## serves the main wiki instead; ##display_error## lets the request reach a wiki that has no descriptor, and XWiki answers ##404## with the ##wikidoesnotexist## template. Its twin takes ##0## for the first and ##1## for the second. | ||
| 92 | |||
| 93 | Creating a page named ##XWiki.WikiDoesNotExist## in the main wiki replaces the standard error message with that page's content. | ||
| 94 |
