Wiki source code of Wiki URL Resolution

Last modified by Eleni Cojocariu on 2026/11/16 18:38

Hide last authors
Eleni Cojocariu 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
Eleni Cojocariu 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
Eleni Cojocariu 2.1 28
29 == Which Form XWiki Writes ==
30
Eleni Cojocariu 5.5 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.urls.switch-domain-based-urls.WebHome]] sets both.
Eleni Cojocariu 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
Eleni Cojocariu 5.2 52 ' ---- XWiki accessible diagram palette (WCAG 2.1 AA): paste verbatim under
53 ' !theme bluegray. Canonical copy: xwiki-doc-writing/tools/ in xwiki-dev-llm.
54 skinparam activity {
55 BackgroundColor #0568AE
56 BorderColor #034873
57 FontColor #FFFFFF
58 StartColor #04538B
59 EndColor #04538B
60 BarColor #5A5A5A
Eleni Cojocariu 5.3 61 ' Diamonds are blue with white text, not light with dark text: a labelled
62 ' `repeat :x;` takes its fill from DiamondBackgroundColor but its font from
63 ' FontColor above, so a light fill draws that one box white on white, and no
64 ' selector reaches it without reaching the decision diamonds too.
65 DiamondBackgroundColor #0568AE
66 DiamondBorderColor #034873
67 DiamondFontColor #FFFFFF
Eleni Cojocariu 5.2 68 }
69 skinparam state {
70 BackgroundColor #0568AE
71 BorderColor #034873
72 FontColor #FFFFFF
73 AttributeFontColor #FFFFFF
74 StartColor #04538B
75 EndColor #04538B
76 }
77 skinparam class {
78 BackgroundColor #0568AE
79 BorderColor #034873
80 FontColor #FFFFFF
81 HeaderBackgroundColor #0568AE
82 AttributeFontColor #FFFFFF
83 StereotypeFontColor #262626
84 }
85 skinparam object {
86 BackgroundColor #0568AE
87 BorderColor #034873
88 FontColor #FFFFFF
89 AttributeFontColor #FFFFFF
90 StereotypeFontColor #262626
91 }
92 skinparam participant {
93 BackgroundColor #0568AE
94 BorderColor #034873
95 FontColor #FFFFFF
96 }
97 skinparam actor {
98 BackgroundColor #F5F5F5
99 BorderColor #5A5A5A
100 FontColor #262626
101 }
102 skinparam component {
103 BackgroundColor #0568AE
104 BorderColor #034873
105 FontColor #FFFFFF
106 }
107 skinparam collections {
108 BackgroundColor #0568AE
109 BorderColor #034873
110 FontColor #FFFFFF
111 }
112 skinparam queue {
113 BackgroundColor #0568AE
114 BorderColor #034873
115 FontColor #FFFFFF
116 }
117 skinparam stack {
118 BackgroundColor #0568AE
119 BorderColor #034873
120 FontColor #FFFFFF
121 }
122 ' database, control, entity, boundary and interface draw their label beside or
123 ' under the icon, on the page, in some diagram types: their text stays dark.
124 skinparam database {
125 BackgroundColor #F5F5F5
126 BorderColor #5A5A5A
127 FontColor #262626
128 }
129 skinparam control {
130 BackgroundColor #0568AE
131 BorderColor #034873
132 FontColor #262626
133 }
134 skinparam entity {
135 BackgroundColor #0568AE
136 BorderColor #034873
137 FontColor #262626
138 }
139 skinparam boundary {
140 BackgroundColor #0568AE
141 BorderColor #034873
142 FontColor #262626
143 }
144 skinparam usecase {
145 BackgroundColor #0568AE
146 BorderColor #034873
147 FontColor #FFFFFF
148 StereotypeFontColor #FFFFFF
149 }
150 skinparam card {
151 BackgroundColor #04538B
152 BorderColor #034873
153 FontColor #FFFFFF
154 }
155 skinparam note {
156 BackgroundColor #04538B
157 BorderColor #034873
158 FontColor #FFFFFF
159 }
160 skinparam storage {
161 BackgroundColor #8A4A00
162 BorderColor #8A4A00
163 FontColor #FFFFFF
164 }
165 skinparam agent {
166 BackgroundColor #8A4A00
167 BorderColor #8A4A00
168 FontColor #FFFFFF
169 }
170 skinparam interface {
171 BackgroundColor #A62222
172 BorderColor #A62222
173 FontColor #262626
174 }
175 skinparam node {
176 BackgroundColor #F5F5F5
177 BorderColor #5A5A5A
178 FontColor #262626
179 }
180 skinparam cloud {
181 BackgroundColor #F5F5F5
182 BorderColor #5A5A5A
183 FontColor #262626
184 }
185 skinparam artifact {
186 BackgroundColor #F5F5F5
187 BorderColor #5A5A5A
188 FontColor #262626
189 }
190 skinparam file {
191 BackgroundColor #F5F5F5
192 BorderColor #5A5A5A
193 FontColor #262626
194 }
195 skinparam rectangle {
196 BackgroundColor #FFFFFF
197 BorderColor #5A5A5A
198 FontColor #262626
199 StereotypeFontColor #0568AE
200 }
201 skinparam folder {
202 BackgroundColor #F5F5F5
203 BorderColor #8A4A00
204 FontColor #8A4A00
205 }
206 skinparam frame {
207 BackgroundColor #F5F5F5
208 BorderColor #04538B
209 FontColor #04538B
210 }
211 skinparam package {
212 BackgroundColor #FFFFFF
213 BorderColor #0568AE
214 FontColor #262626
215 }
216 skinparam partition {
217 BackgroundColor #FFFFFF
218 BorderColor #0568AE
219 FontColor #0568AE
220 }
221 skinparam swimlane {
222 BorderColor #0568AE
223 TitleBackgroundColor #F5F5F5
224 TitleFontColor #0568AE
225 }
226 skinparam sequence {
227 BoxBackgroundColor #F5F5F5
228 BoxBorderColor #5A5A5A
229 BoxFontColor #262626
230 DelayFontColor #262626
231 GroupBorderColor #5A5A5A
232 GroupFontColor #262626
233 LifeLineBorderColor #5A5A5A
234 LifeLineBackgroundColor #F5F5F5
235 TitleFontColor #0568AE
236 StartColor #0568AE
237 EndColor #0568AE
238 BorderColor #0568AE
239 }
240 skinparam arrow {
241 Color #0568AE
242 FontColor #262626
243 }
244 skinparam legend {
245 BackgroundColor #F5F5F5
246 BorderColor #5A5A5A
247 FontColor #262626
248 }
249 skinparam stereotype {
250 CBackgroundColor #F5F5F5
251 CBorderColor #5A5A5A
252 ABackgroundColor #F5F5F5
253 ABorderColor #5A5A5A
254 IBackgroundColor #F5F5F5
255 IBorderColor #5A5A5A
256 EBackgroundColor #F5F5F5
257 EBorderColor #5A5A5A
258 NBackgroundColor #F5F5F5
259 NBorderColor #5A5A5A
260 }
261 skinparam ArrowColor #0568AE
262 ' titleFontColor only: the nested `skinparam title { BackgroundColor }` form
263 ' leaks its background onto every element in the diagram.
264 skinparam titleFontColor #0568AE
265 skinparam titleBorderColor #5A5A5A
266 ' Links otherwise take bluegray's white root colour, unreadable on a light fill.
267 <style>
268 root {
269 HyperLinkColor #0568AE
270 }
271 element {
272 HyperLinkColor #FFFFFF
273 }
274 actor, artifact, boundary, cloud, control, database, entity, file, folder, frame, interface,
275 legend, node, package, rectangle {
276 HyperLinkColor #0568AE
277 }
278 </style>
279 ' ---- end XWiki accessible diagram palette ----
Eleni Cojocariu 2.1 280 skinparam defaultTextAlignment center
281
282 start
283 if (First path segment after the context path) then (wiki)
284 :The alias is the next path segment;
285 if (A descriptor whose server field is the alias) then (found)
286 :Serve that descriptor's wiki;
287 stop
288 endif
289 :Candidate wiki id: the alias;
290 else (bin)
291 :The alias is the host name;
292 if (A descriptor whose server field is the alias) then (found)
293 :Serve that descriptor's wiki;
294 stop
295 endif
296 if (The host is localhost or an IP address,\nor its first label is www) then (yes)
297 :Serve the main wiki;
298 stop
299 endif
300 :Candidate wiki id: the host\nup to the first dot;
301 endif
302
303 if (A descriptor page named after the candidate id) then (found)
304 :Serve that wiki;
305 stop
306 endif
307
308 if (url.standard.multiwiki.notFoundBehavior) then (redirect_to_main_wiki)
309 :Serve the main wiki;
310 else (display_error)
311 :Answer 404,\nthe wiki does not exist;
312 endif
313 stop
314 @enduml
315 {{/plantuml}}
316
317 == When the Wiki Does Not Exist ==
318
319 ##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.
320
321 Creating a page named ##XWiki.WikiDoesNotExist## in the main wiki replaces the standard error message with that page's content.

Get Connected