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

Get Connected