URL API
 | Allows configuration of the URL scheme used by XWiki to parse/serialize URLs |
| Type | JAR |
| Developed by | |
| Active Installs | 0 |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
Table of contents
Description
This module is in charge of parsing/serializing XWiki URLs, based on a URL scheme specified in XWiki's configuration. In general terms the goal of this module is to allow implementing various URL schemes (i.e. various ways to specify XWiki URLs).
Specifically it uses the Resource API module and implements both a ResourceReferenceResolver and a ResourceReferenceSerializer to parse and serialize URLs.
The following schemes are currently implemented:
- standard
- A filesystem URL Scheme has been started for exporting Resources to the filesystem and generating URLs to them (useful for the HTML Export for example). At the moment, only a few Resource Types are using it and most are still using the old XWikiURLFactory implementation classes.
- A reference URL Scheme has been started but is not usable yet. It's meant to implement an Alternate Scheme being proposed in Design.
If you're looking to controlling the URLs you wish to use inside XWiki you should also check the Short URL tutorial, as one solution there is the use of a Rewrite Filter.
Tools
This module also offers some tools that can be reused. Specifically it provides:
- An EntityReferenceResolver<String> resolver and an EntityReferenceSerializer<String> serializer implementations (with hint url) that can be used to parse/serialize EntityReference when used in URLs. The rationale is that Tomcat, for security reasons, doesn't support forward and backward slashes (/, \) in URLs by default. Thus, if a reference contains some reserved characters such as dot (.), colon (:), etc and you use a default serializer they'll be escaped using a backslash, leading to problems under Tomcat. So this resolver/serializer uses a different escape character (namely, it uses !). Example usage:@Inject
@Named("url")
private EntityReferenceResolver<String> urlResolver;
@Inject
@Named("url")
private EntityReferenceSerializer<String> urlSerializer;
@Inject
private EntityReferenceSerializer<String> defaultSerializer;
...
EntityReference reference = this.urlResolver.resolve("Some!.Page.Another page");
assertEquals("Some!.Page.Another page", this.urlSerializer.serialize(reference));
assertEquals("Some\.Page.Another page", this.defaultSerializer.serialize(reference));
Configuration
Scheme
The scheme to use is controlled by the url.format property in xwiki.properties:
#-# The id of the URL format to use. This allows to plug in different implementations and thus allows to completely
#-# control the format of XWiki URLs.
#-#
#-# The default is:
# url.format=standard
In addition, starting with the URL scheme to use is set automatically in the Execution Context and can be modified at runtime. For example:
...
urlContextManager.setURLFormatId("filesystem");
...
String formatId = urlContextManager.getURLFormatId();
...
Resource modification date
Starting with the modification date of local resources can be used as a query parameter in the generated URLs.
In some cases, this might impact the performances of the wiki. You can change this behaviour by editing the url.useResourceLastModificationDate in xwiki.properties:
#-# Whether a the last modified date of the file to be loaded should be checked and put in the URL query parameter.
#-# Disabling this might improve a bit the performance on some old hard drives, or custom filesystem, however
#-# it might imply the need to force-reload some resources in the browser, when migrating.
#-#
#-# The default is:
# url.useResourceLastModificationDate=true
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.
You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.
Dependencies
Dependencies for this extension (org.xwiki.platform:xwiki-platform-url-api 12.10.2):
- org.xwiki.commons:xwiki-commons-configuration-api 12.10.2
- org.xwiki.commons:xwiki-commons-velocity 12.10.2
- org.xwiki.platform:xwiki-platform-resource-default 12.10.2
