Wiki source code of URL Architecture

Last modified by Simon Urli on 2023/12/07

version	line-number	content
3.1	1	{{box cssClass="floatinginfobox" title="Contents"}}
	2	{{toc/}}
	3	{{/box}}
	4
1.1	5	This is how URLs are handled when entering an XWiki instance:
	6
16.2	7	{{plantuml}}
12.2	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
16.2	40	{{/plantuml}}
12.2	41
1.1	42	Specifically:
9.1	43
18.2	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.
1.1	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
3.2	49	= Standard URL Scheme =
3.1	50
19.2	51	This is the default URL format used by XWiki. See [[Standard URL Scheme>>Standard URL Format]].
3.1	52
3.2	53	= Customizing URLs =
1.1	54
	55	There are several solutions to customize XWiki URLs:
9.1	56
19.2	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]].
1.1	59	* You can implement a new URL Scheme. See the [[URL API>>extensions:Extension.URL API]].
6.1	60	* You can simply register new Resource Types or new Entity Actions. See the [[Resource API>>extensions:Extension.Resource API]].
1.1	61
	62	{{info}}
20.1	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]].
8.1	64
	65	[[Here's an example of writing a custom ##class-rule##>>https://github.com/xwiki-contrib/url-rewrite-reference]].
1.1	66	{{/info}}
	67
12.1	68	= Legacy Actions Servlet Architecture =
4.1	69
12.1	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:
4.1	71
16.3	72	{{plantuml}}
14.1	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
16.3	106	{{/plantuml}}
4.1	107
14.1	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}}(((
19.1	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}}
14.1	114	)))
19.2	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.
4.1	116	* ##ViewAction## specifies that ##view.vm## will be rendered using Velocity
	117	* The space asked is ##Main## and the document's name is ##WebHome##
19.1	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
20.1	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	)))

Wiki source code of URL Architecture

Quick Links

Navigation

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected