URL Architecture (XWiki.org)

* 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]].

= Customizing URLs =

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

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

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:

@startuml

!theme bluegray

start

: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""

* ""XWiki""

* ""XWikiRequest""

* ""XWikiResponse""

* ...

end note

floating note right

The called Action is a component with a

89

hint equals to the URL part representing

90

the action (e.g. ""edit"" for ""EditAction"")

end note

split

:View Action;

:Renders view.vm;

split again

:Save Action;

:Renders save.vm;

split again

:Other Actions;

:Renders other Velocity

template files;

end split

:Service APIs

(exposed in the context);

@enduml

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

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

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##

= Redirections =

* 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

)))

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

author	version	line-number	content
		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	)))