org.xwiki.platform:xwiki-platform-url-apiXWiki Platform - URL - APIjar00.0XWiki Platform - URL - API{{info}}
Even though it's already in use, this module is still in its infancy and the serialization part is not fully implemented yet.
{{/info}}
This module is in charge of
* parsing/serializing XWiki URLs, based on a URL scheme specified in XWiki's configuration,
* {{version since="12.10.7,13.3RC1"}}handling security of external URLs {{/version}}
= URLs schemes =
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##>>Extension.Standard URL Scheme]]
* 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>>design:Design.AlternateURLScheme]].
If you're looking to controlling the URLs you wish to use inside XWiki you should also check the [[Short URL tutorial>>xwiki:Documentation.AdminGuide.ShortURLs]], as one solution there is the use of a Rewrite Filter.
= API Examples =
Extracts the ##EntityReference## pointed to by an XWiki URL, following the defined URL Scheme:
{{code language="none"}}
import org.xwiki.resource.entity.EntityResourceReference;
...
@Inject
private ResourceTypeResolver<ExtendedURL> typeResolver;
@Inject
private ResourceReferenceResolver<ExtendedURL> resourceResolver;
...
// context is an XWikiContext object
URL url = context.getURL();
ExtendedURL extendedURL = new ExtendedURL(url, context.getRequest().getContextPath());
ResourceType type = typeResolver.resolve(extendedURL, Collections.<String, Object>emptyMap());
ResourceReference reference = resourceResolver.resolve(extendedURL, type, Collections.<String, Object>emptyMap());
if (reference instanceof EntityResourceReference) {
EntityReference entityReference = ((EntityResourceReference) reference).getEntityReference();
...
}
{{/code}}
= 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:(((
{{code}}
@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));
{{/code}}
)))
= Configuration =
== Scheme ==
The scheme to use is controlled by the ##url.format## property in ##xwiki.properties##:
{{code}}
#-# [Since 5.1M1]
#-# 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
{{/code}}
In addition, starting with {{info}}XWiki 7.2M1{{/info}} the URL scheme to use is set automatically in the Execution Context and can be modified at runtime. For example:
{{code language="java"}}
@Inject private URLContextManager urlContextManager;
...
urlContextManager.setURLFormatId("filesystem");
...
String formatId = urlContextManager.getURLFormatId();
...
{{/code}}
== Resource modification date ==
Starting with {{info}}XWiki 11.1RC1{{/info}} 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##:
{{code}}
#-# [Since 11.1RC1]
#-# 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
{{/code}}
= Security =
{{version since="12.10.7,13.3RC1"}}
This module is also in charge of handling the security of external URLs with a dedicated component ##URLSecurityManager##:
{{remotecode language="java" source="https://raw.githubusercontent.com/xwiki/xwiki-platform/master/xwiki-platform-core/xwiki-platform-url/xwiki-platform-url-api/src/main/java/org/xwiki/url/URLSecurityManager.java" /}}
{{/version}}
== Script service ==
{{version since="15.0,14.10.4"}}
A dedicated script service has been introduced to allow access of the security URL APIs:
{{remotecode language="java" source="https://raw.githubusercontent.com/xwiki/xwiki-platform/master/xwiki-platform-core/xwiki-platform-url/xwiki-platform-url-api/src/main/java/org/xwiki/url/script/URLSecurityScriptService.java" /}}
{{/version}}
== Configuration ==
A few configuration are available in ##xwiki.properties## for handling the security of URLs:
{{code language="none"}}
#-# [Since 13.3RC1]
#-# [Since 12.10.7]
#-# Define a list of trusted domains that can be used in the wiki for performing requests or redirections even if
#-# the wiki does not use it. Domains are listed without http and separated with a comma in the list. Subdomains can be
#-# specified.
#-# Example of accepted value: foo.acme.org,enterprise.org
#-#
#-# By default the list of trusted domains is empty:
# url.trustedDomains=
#-# [Since 13.3RC1]
#-# [Since 12.10.7]
#-# Allow to enable or disable checks performed on domains by taking into account the list of trusted domains.
#-# Disable this property only if you experienced some issues on your wiki: some security check won't be performed when
#-# this property is set to false.
#-#
#-# By default this property is set to true:
# url.trustedDomainsEnabled=true
#-# [Since 15.0]
#-# [Since 14.10.4]
#-# Define the list of schemes that are allowed for trusted URIs. Those schemes are checked whenever an absolute URI
#-# needs to be checked (e.g. before performing a redirect). Any URI whose scheme doesn't belong to that list will not
#-# be considered trustful, even if the domain of the URI is trusted.
#-# Also note that even if a protocol is added here to be trusted, it might need a custom protocol handler. By default,
#-# only http,https,ftp and file protocols are handled.
#-#
#-# The default is:
# url.trustedSchemes=http,https,ftp
#-# [Since 17.0.0]
#-# By default, XWiki will try its best to force the application server to let any URL go through despite their default
#-# protections and what Servlet 6.0 recommend.
#-# The point of this option is to allow disabling this bypass of the application server default protections.
#-# For example, if you are using the same application server for something else than XWiki.
#-#
#-# The default is:
# url.forceAllowAnyCharacter=true
#-# [Since 17.9.0]
#-# [Since 17.4.7]
#-# [Since 16.10.14]
#-# Define the policy to use for URL checks performed in the UI, whether the user should be asked for confirmation
#-# when going to an untrusted domain.
#-# Accepted values for this property are: enabled, disabled, or comments.
#-# Enabled means that the check will be enforced in all the wiki UI, disabled that the check will never be
#-# performed, and comments (default value) means that the check will only be performed on links provided in the
#-# comments of the wiki.
#-#
#-# By default this property is set to comments:
# url.frontendUrlCheckPolicy=comments
#-# [Since 17.9.0RC1]
#-# [Since 17.4.6]
#-# [Since 16.10.13]
#-# Allow to allow specific URLs to be accessible from the frontend without asking confirmation, and without
#-# needing to allow and entire domain. The expected format is absolute URLs separated by commas, e.g.:
#-# https://github.com/xwiki/xwiki-platform,https://www.xwiki.org/xwiki/bin/view/Main/WebHome
#-#
#-# By default this property is empty:
# url.allowedFrontendUrls=
{{code}}
GNU Lesser General Public License 2.1http://extensions.xwiki.org/xwiki/bin/view/Extension/URL%20APIXWiki Development Teamhttps://xwiki.org/xwiki/bin/view/XWiki/XWikiTeamgitgit://github.com/xwiki/xwiki-platform.git/xwiki-platform-core/xwiki-platform-url/xwiki-platform-url-apigitgit@github.com:xwiki/xwiki-platform.git/xwiki-platform-core/xwiki-platform-url/xwiki-platform-url-apihttps://github.com/xwiki/xwiki-platform/tree/master/xwiki-platform-core/xwiki-platform-url/xwiki-platform-url-api/jirahttps://jira.xwiki.org/browse/XWIKIapifalsemaven.groupidorg.xwiki.platformmaven.artifactidxwiki-platform-url-apimaven.Modelorg.xwiki.platform:xwiki-platform-url-api:jar:18.7.0xwiki.extension.recommendedVersions.commonsorg.xwiki.commons:.*/[18.7.0]xwiki.extension.recommendedVersions.platformorg.xwiki.commons:.*/[18.7.0],
org.xwiki.rendering:.*/[18.7.0],
org.xwiki.platform:.*/[18.7.0]xwiki.extension.recommendedVersionsorg.xwiki.commons:.*/[18.7.0],
org.xwiki.rendering:.*/[18.7.0],
org.xwiki.platform:.*/[18.7.0]4.4maven-xwikihttps://nexus.xwiki.org/nexus/content/groups/publicmaven