Wiki source code of Short URLs

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

Hide last authors
Eleni Cojocariu 2.1 1 A short URL is an XWiki URL without its ##xwiki##, ##bin## and ##view## parts: ##server.com/Sandbox/WebHome## instead of ##server.com/xwiki/bin/view/Sandbox/WebHome##. Shortening them changes both the URLs XWiki accepts and the URLs it generates.
2
3 == The three parts to remove ==
4
5 A default XWiki URL carries three removable parts, each removed by a different mechanism. They are independent, so you can remove one, two or all three.
6
7 |=Part|=Example|=What it is|=How to remove it
Eleni Cojocariu 9.5 8 |Application name|##/xwiki/##|The context path the servlet container gives the XWiki web application.|[[Deploy XWiki as the Root Web Application>>doc:documentation.xs.admin.urls.short-urls.deploy-root-webapp.WebHome]]
Eleni Cojocariu 2.1 9 |Servlet mapping|##/bin/##|The path the Action Servlet is mapped to, which tells the container which servlet handles the request.|One of the two approaches below.
Eleni Cojocariu 9.9 10 |Action name|##/view/##|What to do with the document: view, edit, delete, and so on.|[[Hide the View Action in URLs>>doc:documentation.xs.admin.urls.short-urls.hide-view-action.WebHome]]
Eleni Cojocariu 2.1 11
Eleni Cojocariu 9.10 12 Every configuration key these pages set is listed on [[URL Configuration Properties>>doc:documentation.xs.admin.urls.short-urls.properties.WebHome]].
Eleni Cojocariu 2.1 13
14 == Removing the servlet mapping ==
15
16 This is the only part that configuration alone cannot remove. XWiki maps its Action Servlet to ##/bin/*##, ##/wiki/*## (the prefix of path-based subwikis), ##/testbin/*## and ##/xwiki/*##, so a request carrying none of them has to be rewritten into one of them before it reaches the servlet. Two places can do that, which is the choice to make:
17
Eleni Cojocariu 9.6 18 * [[Configure Short URLs with the UrlRewriteFilter>>doc:documentation.xs.admin.urls.short-urls.rewrite-filter.WebHome]], a servlet filter installed inside the XWiki web application. Use it when nothing sits in front of XWiki.
Eleni Cojocariu 9.8 19 * [[Configure Short URLs with Apache HTTP Server>>doc:documentation.xs.admin.urls.short-urls.apache.WebHome]] or [[Configure Short URLs with Nginx>>doc:documentation.xs.admin.urls.short-urls.nginx.WebHome]], where the web server rewrites the path before the request reaches the servlet container. Use one of these when the instance is already behind that web server.
Eleni Cojocariu 2.1 20
21 {{plantuml}}
22 @startuml
23 !theme bluegray
Eleni Cojocariu 9.2 24 ' ---- XWiki accessible diagram palette (WCAG 2.1 AA): paste verbatim under
25 ' !theme bluegray. Canonical copy: xwiki-doc-writing/tools/ in xwiki-dev-llm.
26 skinparam activity {
27 BackgroundColor #0568AE
28 BorderColor #034873
29 FontColor #FFFFFF
30 StartColor #04538B
31 EndColor #04538B
32 BarColor #5A5A5A
Eleni Cojocariu 9.3 33 ' Diamonds are blue with white text, not light with dark text: a labelled
34 ' `repeat :x;` takes its fill from DiamondBackgroundColor but its font from
35 ' FontColor above, so a light fill draws that one box white on white, and no
36 ' selector reaches it without reaching the decision diamonds too.
37 DiamondBackgroundColor #0568AE
38 DiamondBorderColor #034873
39 DiamondFontColor #FFFFFF
Eleni Cojocariu 9.2 40 }
41 skinparam state {
42 BackgroundColor #0568AE
43 BorderColor #034873
44 FontColor #FFFFFF
45 AttributeFontColor #FFFFFF
46 StartColor #04538B
47 EndColor #04538B
48 }
49 skinparam class {
50 BackgroundColor #0568AE
51 BorderColor #034873
52 FontColor #FFFFFF
53 HeaderBackgroundColor #0568AE
54 AttributeFontColor #FFFFFF
55 StereotypeFontColor #262626
56 }
57 skinparam object {
58 BackgroundColor #0568AE
59 BorderColor #034873
60 FontColor #FFFFFF
61 AttributeFontColor #FFFFFF
62 StereotypeFontColor #262626
63 }
64 skinparam participant {
65 BackgroundColor #0568AE
66 BorderColor #034873
67 FontColor #FFFFFF
68 }
69 skinparam actor {
70 BackgroundColor #F5F5F5
71 BorderColor #5A5A5A
72 FontColor #262626
73 }
74 skinparam component {
75 BackgroundColor #0568AE
76 BorderColor #034873
77 FontColor #FFFFFF
78 }
79 skinparam collections {
80 BackgroundColor #0568AE
81 BorderColor #034873
82 FontColor #FFFFFF
83 }
84 skinparam queue {
85 BackgroundColor #0568AE
86 BorderColor #034873
87 FontColor #FFFFFF
88 }
89 skinparam stack {
90 BackgroundColor #0568AE
91 BorderColor #034873
92 FontColor #FFFFFF
93 }
94 ' database, control, entity, boundary and interface draw their label beside or
95 ' under the icon, on the page, in some diagram types: their text stays dark.
96 skinparam database {
97 BackgroundColor #F5F5F5
98 BorderColor #5A5A5A
99 FontColor #262626
100 }
101 skinparam control {
102 BackgroundColor #0568AE
103 BorderColor #034873
104 FontColor #262626
105 }
106 skinparam entity {
107 BackgroundColor #0568AE
108 BorderColor #034873
109 FontColor #262626
110 }
111 skinparam boundary {
112 BackgroundColor #0568AE
113 BorderColor #034873
114 FontColor #262626
115 }
116 skinparam usecase {
117 BackgroundColor #0568AE
118 BorderColor #034873
119 FontColor #FFFFFF
120 StereotypeFontColor #FFFFFF
121 }
122 skinparam card {
123 BackgroundColor #04538B
124 BorderColor #034873
125 FontColor #FFFFFF
126 }
127 skinparam note {
128 BackgroundColor #04538B
129 BorderColor #034873
130 FontColor #FFFFFF
131 }
132 skinparam storage {
133 BackgroundColor #8A4A00
134 BorderColor #8A4A00
135 FontColor #FFFFFF
136 }
137 skinparam agent {
138 BackgroundColor #8A4A00
139 BorderColor #8A4A00
140 FontColor #FFFFFF
141 }
142 skinparam interface {
143 BackgroundColor #A62222
144 BorderColor #A62222
145 FontColor #262626
146 }
147 skinparam node {
148 BackgroundColor #F5F5F5
149 BorderColor #5A5A5A
150 FontColor #262626
151 }
152 skinparam cloud {
153 BackgroundColor #F5F5F5
154 BorderColor #5A5A5A
155 FontColor #262626
156 }
157 skinparam artifact {
158 BackgroundColor #F5F5F5
159 BorderColor #5A5A5A
160 FontColor #262626
161 }
162 skinparam file {
163 BackgroundColor #F5F5F5
164 BorderColor #5A5A5A
165 FontColor #262626
166 }
167 skinparam rectangle {
168 BackgroundColor #FFFFFF
169 BorderColor #5A5A5A
170 FontColor #262626
171 StereotypeFontColor #0568AE
172 }
173 skinparam folder {
174 BackgroundColor #F5F5F5
175 BorderColor #8A4A00
176 FontColor #8A4A00
177 }
178 skinparam frame {
179 BackgroundColor #F5F5F5
180 BorderColor #04538B
181 FontColor #04538B
182 }
183 skinparam package {
184 BackgroundColor #FFFFFF
185 BorderColor #0568AE
186 FontColor #262626
187 }
188 skinparam partition {
189 BackgroundColor #FFFFFF
190 BorderColor #0568AE
191 FontColor #0568AE
192 }
193 skinparam swimlane {
194 BorderColor #0568AE
195 TitleBackgroundColor #F5F5F5
196 TitleFontColor #0568AE
197 }
198 skinparam sequence {
199 BoxBackgroundColor #F5F5F5
200 BoxBorderColor #5A5A5A
201 BoxFontColor #262626
202 DelayFontColor #262626
203 GroupBorderColor #5A5A5A
204 GroupFontColor #262626
205 LifeLineBorderColor #5A5A5A
206 LifeLineBackgroundColor #F5F5F5
207 TitleFontColor #0568AE
208 StartColor #0568AE
209 EndColor #0568AE
210 BorderColor #0568AE
211 }
212 skinparam arrow {
213 Color #0568AE
214 FontColor #262626
215 }
216 skinparam legend {
217 BackgroundColor #F5F5F5
218 BorderColor #5A5A5A
219 FontColor #262626
220 }
221 skinparam stereotype {
222 CBackgroundColor #F5F5F5
223 CBorderColor #5A5A5A
224 ABackgroundColor #F5F5F5
225 ABorderColor #5A5A5A
226 IBackgroundColor #F5F5F5
227 IBorderColor #5A5A5A
228 EBackgroundColor #F5F5F5
229 EBorderColor #5A5A5A
230 NBackgroundColor #F5F5F5
231 NBorderColor #5A5A5A
232 }
233 skinparam ArrowColor #0568AE
234 ' titleFontColor only: the nested `skinparam title { BackgroundColor }` form
235 ' leaks its background onto every element in the diagram.
236 skinparam titleFontColor #0568AE
237 skinparam titleBorderColor #5A5A5A
238 ' Links otherwise take bluegray's white root colour, unreadable on a light fill.
239 <style>
240 root {
241 HyperLinkColor #0568AE
242 }
243 element {
244 HyperLinkColor #FFFFFF
245 }
246 actor, artifact, boundary, cloud, control, database, entity, file, folder, frame, interface,
247 legend, node, package, rectangle {
248 HyperLinkColor #0568AE
249 }
250 </style>
251 ' ---- end XWiki accessible diagram palette ----
Eleni Cojocariu 2.1 252 skinparam nodesep 30
253 skinparam ranksep 45
254
255 actor "Browser requests\nserver.com/Sandbox/WebHome" as B
256 rectangle "Apache HTTP Server or Nginx\nrewrites the path" as WS
257 rectangle "UrlRewriteFilter\nin the XWiki web application\nrewrites the path" as F
258 rectangle "Action Servlet\nmapped to /bin/*" as A
259 card "Sandbox.WebHome is displayed" as P
260
261 B --> WS : XWiki already behind a web server
262 B --> F : nothing in front of XWiki
263 WS --> A : /bin/view/Sandbox/WebHome
264 F --> A : /bin/view/Sandbox/WebHome
265 A --> P
266 @enduml
267 {{/plantuml}}
268
269 == What must not reach the Action Servlet ==
270
271 Whatever performs the rewriting has to leave alone the paths XWiki serves by other means, or it breaks static resources, the REST API and file uploads.
272
273 |=Path|=Why it must be excluded
274 |##resources##, ##skins##|Static resource types, which XWiki deliberately lets fall through to the servlet container's default servlet.
275 |##webjars##, ##tmp##|Resource types with their own handlers: web application libraries, and temporary resources such as generated diagrams.
276 |##rest##|The REST API, served by its own servlet.
277 |##redirect##|The web application's welcome file, which sends a URL carrying no page to the home page.
Eleni Cojocariu 5.1 278 |##bin##, ##wiki##, ##testbin##, ##xwiki##|Already mapped to the Action Servlet.
279 |##asyncrenderer##, ##authenticate##, ##jcaptcha##, ##job##|Each is claimed by another resource handler.
280 |##websocket##|The prefix of the WebSocket end-points, which the realtime editing features connect to.
281 |##robots.txt##|Served as a static file when the instance provides one.
Eleni Cojocariu 2.1 282
283 == Why a single catch-all mapping is not enough ==
284
Eleni Cojocariu 5.1 285 The obvious shortcut is to map the Action Servlet to ##/*## in ##web.xml## and change nothing else. It does not work: ##/skins## and ##/resources## match that mapping too, and ##web.xml## leaves them unmapped precisely so that the container's default servlet serves them. Excluding them in the rewrite rules, or serving them from the web server in front of XWiki, is what the two approaches above do instead. Mapping the two paths to the container's own default servlet is not a way out either: on Tomcat that servlet takes no parameter for changing the directory it serves from, so you would have to write one of your own.
Eleni Cojocariu 2.1 286
287 == What you end up with ==
288
289 |=URL|=Page shown
290 |##server.com/Sandbox/WebHome##|##Sandbox.WebHome##
291 |##server.com/Sandbox/##|##Sandbox.WebHome##
Eleni Cojocariu 5.1 292 |##server.com/Document##|##Document.WebHome##
Eleni Cojocariu 2.1 293 |##server.com/##|##Main.WebHome##

Get Connected