Wiki source code of URL Architecture
Version 14.1 by Vincent Massol on 2021/06/08
Show last authors
| 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 | {{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="xwiki-struts.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## |
