Wiki source code of URL Architecture

Last modified by Simon Urli on 2023/12/07

Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 This is how URLs are handled when entering an XWiki instance:
6
7 {{plantuml}}
8 @startuml
9 !theme bluegray
10 start
11 -> URL;
12 :Routing Filter;
13 floating note left
14 Executed as the first
15 Filter in web.xml
16 end note
17 floating note right
18 Parse URL and check if there's
19 a Resource Reference Handler to
20 handle the Resource Type
21 end note
22 if (Resource Reference Filter?) then (Yes)
23 :Resource Reference Handler Servlet;
24 :Resource Reference Handler;
25 note: e.g. WebJarsResourceReferenceHandler
26 kill
27 else (No)
28 partition "Legacy Action Handling" {
29 :Evaluate rest of web.xml;
30 split
31 :Legacy Action Servlet;
32 kill
33 split again
34 :Other Servlets;
35 kill
36 end split
37 }
38 endif
39 @enduml
40 {{/plantuml}}
41
42 Specifically:
43
44 * 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.
45 * 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.
46
47 For more details see the [[Resource API>>extensions:Extension.Resource API]] and the [[URL API>>extensions:Extension.URL API]] reference documentation.
48
49 = Standard URL Scheme =
50
51 This is the default URL format used by XWiki. See [[Standard URL Scheme>>Standard URL Format]].
52
53 = Customizing URLs =
54
55 There are several solutions to customize XWiki URLs:
56
57 * You can tune them to some degree by modifying XWiki's configuration. The various options are described in the [[Short URL documentation>>xwiki:Documentation.AdminGuide.ShortURLs]].
58 * You can rewrite both incoming URLs but also outbound URLs using a Rewrite Filter. An example is also provided in the [[Short URL documentation>>xwiki:Documentation.AdminGuide.ShortURLs]].
59 * You can implement a new URL Scheme. See the [[URL API>>extensions:Extension.URL API]].
60 * You can simply register new Resource Types or new Entity Actions. See the [[Resource API>>extensions:Extension.Resource API]].
61
62 {{info}}
63 Note that using Tuckey's [[Rewrite Filter>>http://tuckey.org/urlrewrite/]] is very powerful as it also allows using dynamic rules written in Java by using the [[##<class-rule~>##>>http://tuckey.org/urlrewrite/manual/4.0/index.html#class-rule]] feature. However, [[dynamic outbound rules are not yet possible>>https://code.google.com/p/urlrewritefilter/issues/detail?id=73]].
64
65 [[Here's an example of writing a custom ##class-rule##>>https://github.com/xwiki-contrib/url-rewrite-reference]].
66 {{/info}}
67
68 = Legacy Actions Servlet Architecture =
69
70 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:
71
72 {{plantuml}}
73 @startuml
74 !theme bluegray
75 start
76 :Legacy Action Servlet;
77 floating note: Configured in ""WEB-INF/web.xml""
78 :Initialize XWiki;
79 floating note left
80 Initialize XWiki objects:
81 * ""XWikiContext"" / ""ExecutionContext""
82 * ""XWiki""
83 * ""XWikiRequest""
84 * ""XWikiResponse""
85 * ...
86 end note
87 floating note right
88 The called Action is a component with a
89 hint equals to the URL part representing
90 the action (e.g. ""edit"" for ""EditAction"")
91 end note
92 split
93 :View Action;
94 :Renders view.vm;
95 split again
96 :Save Action;
97 :Renders save.vm;
98 split again
99 :Other Actions;
100 :Renders other Velocity
101 template files;
102 end split
103 :Service APIs
104 (exposed in the context);
105 @enduml
106 {{/plantuml}}
107
108 For example for the ##http:~/~/www.xwiki.org/xwiki/bin/view/Main/WebHome## URL for the ##standard## URL scheme, the following happens:
109
110 * {{version since="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##{{/version}}(((
111 {{version before="13.0"}}
112 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##.
113 {{/version}}
114 )))
115 * The wiki is the main wiki in this example (since the server name starts by ##www##). See [[Accessing a wiki>>xwiki:Documentation.AdminGuide.AccessWiki]] for more details on how wikis are accessed from URLs.
116 * ##ViewAction## specifies that ##view.vm## will be rendered using Velocity
117 * The space asked is ##Main## and the document's name is ##WebHome##
118
119 = Redirections =
120
121 * 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##.
122 * Redirection can also be defined programmatically, see [[How to add a redirect?>>doc:FAQ.Adding a redirect]]
123
124 {{version since="14.0RC1"}}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.{{/version}}
125
126
127 (% class="box infomessage" %)
128 (((
129 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.
130 )))

Get Connected