Allows creation of absolute URLs (i.e. including scheme and host) used outside the context of HTML (where all URLs should be relative). A typical example would be an RSS feed link: http://server.com/feed.xml . Since instances itself cannot know their externally visible URL if they are running behind a web layer, and sometimes those links have to be created outside of the request scope, this service provides a central place to configure those external URLs and build them.

Details

There are the following options:

create an absolute URL to any configured server identified by a simple name - based on configuration via the externalLink , publishLink and authorLink methods; the domain can be one of these:

PUBLISH "publish" - the public facing website DNS

AUTHOR "author" - the authoring system DNS

LOCAL "local" - the local instance

or any custom configured domain

create an absolute URL based on the host dynamically provided in the current request with absoluteLink (not recommended for most use cases)

create a relative URL that is relative to the current request using relativeLink (provided for convenience, same as ResourceResolver#map )

These elements are considered:

host name

port (80 for http and 443 for https will be skipped)

context path of the sling webapp

scheme - usually defined by the caller (e.g. if it creates an "ftp" or "webcal" link), but the configuration should contain a default scheme (http or https) to indicate whether SSL is used by default or not for normal http links; in that case use one of the methods without a scheme argument

sling mappings - done by passing a ResourceResolver ; also includes namespace mangling ( jcr:content becomes _jcr_content)

Examples

Can be retrieved as a normal OSGi service: @Reference Externalizer externalizer; It can also be adapted from a ResourceResolver : Externalizer externalizer = resourceResolver.adaptTo(Externalizer.class); Always pass a raw resource path. It might contain an extension, URL query and/or fragment part already, but it is best to add those after the call: // public facing website externalizer.publishLink(resolver, "/my/page") + ".html"; // => "http://www.website.com/contextpath/my/page.html" externalizer.publishLink(resolver, "webcal", "/my/cal") + ".ics"; // => "webcal://www.website.com/contextpath/my/cal.ics" externalizer.publishLink(resolver, "/my/path?query=part#fragment"); // => "http://www.website.com/contextpath/my/path?query=part#fragment" // link to author externalizer.authorLink(resolver, "/my/page") + ".html"; // => "http://author.website.com/contextpath/my/page.html" // direct link to instance itself externalizer.externalLink(resolver, Externalizer.LOCAL, "/my/page") + ".html"; // => "http://publish-3.internal/contextpath/my/page.html" // custom configured domain externalizer.externalLink(resolver, "mydomain", "/my/page") + ".html"; // => "http://mydomain.com/my/page.html" // absolute link based on the request externalizer.absoluteLink(slingRequest, "http", "/my/path"); // => "http://host.com/contextpath/my/path" // relative links always require the request object externalizer.relativeLink(slingRequest, "/my/path"); // => "/contextpath/my/path"

Note about the link checker for HTML

For basic <a> and <area> links in HTML, the CQ link checker will automatically run ResourceResolver#map(request, path) to handle mappings, the context path and namespace mangling. The same applies to href , src and action attributes on any HTML element. For those HTML cases this utility should not be used , as no absolute links should be created in the context of HTML. If relative URLs need to be written in places that are not covered by the link checker, such as generated Javascript or CSS, use ResourceResolver#map(request, path) manually (or relativeLink , which is the same). However, any link that was already sent through this utility should also go through untouched by the link checker an additional time (but only seen as valid if the resource exists).

absoluteLink ​( ResourceResolver resolver, java.lang.String scheme, java.lang.String path)