com.day.cq.commons
Interface Externalizer

public interface Externalizer

Service interface to externalize URLs.

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:

1. 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
2. create an absolute URL based on the host dynamically provided in the current request with absoluteLink (not recommended for most use cases)
3. 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).

Field Summary

static String	AUTHOR Name for domain configuration that contains the author DNS address.
static String	LOCAL Name for domain configuration that contains the instance's local address.
static String	PUBLISH Name for domain configuration that contains the public website DNS address.

Method Summary

String	absoluteLink(ResourceResolver resolver, String scheme, String path) Deprecated. since 5.5, use externalLink(resolver, Externalizer.LOCAL, scheme, path) instead
String	absoluteLink(SlingHttpServletRequest request, String scheme, String path) Externalizes the given resource path as an absolute URL based on the request.
String	absoluteLink(String scheme, String path) Deprecated. since 5.5, use externalLink(null, Externalizer.LOCAL, scheme, path) instead
String	authorLink(ResourceResolver resolver, String path) Creates an absolute URL for the authoring system.
String	authorLink(ResourceResolver resolver, String scheme, String path) Creates an absolute URL for the authoring system.
String	externalLink(ResourceResolver resolver, String domain, String path) Creates an absolute URL for a named domain.
String	externalLink(ResourceResolver resolver, String domain, String scheme, String path) Creates an absolute URL for a named domain.
String	publishLink(ResourceResolver resolver, String path) Creates an absolute URL for the public website.
String	publishLink(ResourceResolver resolver, String scheme, String path) Creates an absolute URL for the public website.
String	relativeLink(SlingHttpServletRequest request, String path) Externalizes the given resource path relative to the URL of the request.

Field Detail

LOCAL

static final String LOCAL

Name for domain configuration that contains the instance's local address. For example http://author-1.internal:4502 or http://publish-3.internal:4503.

See Also:

Constant Field Values

AUTHOR

static final String AUTHOR

Name for domain configuration that contains the author DNS address. For example http://author.website.com.

See Also:

Constant Field Values

PUBLISH

static final String PUBLISH

Name for domain configuration that contains the public website DNS address. For example http://www.website.com.

See Also:

Constant Field Values

Method Detail

externalLink

String externalLink(ResourceResolver resolver,
                    String domain,
                    String path)

Creates an absolute URL for a named domain. Uses the configured default scheme of that domain, or "http".

Use the standard LOCAL, PUBLISH or AUTHOR domains. Custom ones are also possible.

Parameters:

resolver - a resource resolver for handling the sling mappings and namespace mangling; can be null

domain - name of the domain configuration to use

path - a resource path; might contain extension, query or fragment, but plain paths are recommended; has to be without context path

Returns:

an absolute URL string

Since:

5.5

See Also:

publishLink(ResourceResolver, String), authorLink(ResourceResolver, String)

externalLink

String externalLink(ResourceResolver resolver,
                    String domain,
                    String scheme,
                    String path)

Creates an absolute URL for a named domain. Uses the scheme passed as argument.

Use the standard LOCAL, PUBLISH or AUTHOR domains. Custom ones are also possible.

Parameters:

resolver - a resource resolver for handling the sling mappings and namespace mangling; can be null

domain - name of the domain configuration to use

scheme - a protocol scheme such as "http", that will be part of the URL

path - a resource path; might contain extension, query or fragment, but plain paths are recommended; has to be without context path

Returns:

an absolute URL string

Since:

5.5

See Also:

publishLink(ResourceResolver, String, String), authorLink(ResourceResolver, String, String)

publishLink

String publishLink(ResourceResolver resolver,
                   String path)

Creates an absolute URL for the public website. Uses the configured default scheme of that domain, or "http".

Shortcut for externalLink(resolver, Externalizer.PUBLISH, path).

Parameters:

resolver - a resource resolver for handling the sling mappings and namespace mangling; can be null

path - a resource path; might contain extension, query or fragment, but plain paths are recommended; has to be without context path

Returns:

an absolute URL string

Since:

5.5

See Also:

externalLink(ResourceResolver, String, String)

publishLink

String publishLink(ResourceResolver resolver,
                   String scheme,
                   String path)

Creates an absolute URL for the public website. Uses the scheme passed as argument.

Shortcut for externalLink(resolver, Externalizer.PUBLISH, scheme, path).

Parameters:

resolver - a resource resolver for handling the sling mappings and namespace mangling; can be null

scheme - a protocol scheme such as "http", that will be part of the URL

path - a resource path; might contain extension, query or fragment, but plain paths are recommended; has to be without context path

Returns:

an absolute URL string

Since:

5.5

See Also:

externalLink(ResourceResolver, String, String, String)

authorLink

String authorLink(ResourceResolver resolver,
                  String path)

Creates an absolute URL for the authoring system. Uses the configured default scheme of that domain, or "http".

Shortcut for externalLink(resolver, Externalizer.AUTHOR, path).

Parameters:

resolver - a resource resolver for handling the sling mappings and namespace mangling; can be null

path - a resource path; might contain extension, query or fragment, but plain paths are recommended; has to be without context path

Returns:

an absolute URL string

Since:

5.5

See Also:

externalLink(ResourceResolver, String, String)

authorLink

String authorLink(ResourceResolver resolver,
                  String scheme,
                  String path)

Creates an absolute URL for the authoring system. Uses the scheme passed as argument.

Shortcut for externalLink(resolver, Externalizer.AUTHOR, scheme, path).

Parameters:

resolver - a resource resolver for handling the sling mappings and namespace mangling; can be null

scheme - a protocol scheme such as "http", that will be part of the URL

path - a resource path; might contain extension, query or fragment, but plain paths are recommended; has to be without context path

Returns:

an absolute URL string

Since:

5.5

See Also:

externalLink(ResourceResolver, String, String, String)

relativeLink

String relativeLink(SlingHttpServletRequest request,
                    String path)

Externalizes the given resource path relative to the URL of the request.

Note: This is exactly the same as request.getResourceResolver().map(request, path).

Note that the result might be an absolute URL if the sling mappings define an explicit hostname and the current request's hostname is different.

Parameters:

request - a sling http request object (required for context path and sling resource resolver mapping)

path - a resource path; might contain extension, query or fragment, but plain paths are recommended; has to be without context path

Returns:

an fully qualified URL string that is relative to the given request; it might be an absolute URL if the resource path is mapped to a different host than the current request

absoluteLink

String absoluteLink(SlingHttpServletRequest request,
                    String scheme,
                    String path)

Externalizes the given resource path as an absolute URL based on the request. The hostname (and port) are taken from the resource resolver mapping configuration, if present, or dynamically from the current request using ServletRequest.getServerName() and ServletRequest.getServerPort(), while the scheme is given as argument.

Use with care, as this is request dependent: the host header might not be what is expected.

Parameters:

request - a sling http request object (required for host, port, context path and sling resource resolver mapping)

scheme - a protocol scheme such as "http", that will be part of the URL

path - a resource path; might contain extension, query or fragment, but plain paths are recommended; has to be without context path

Returns:

an absolute URL string

absoluteLink

@Deprecated
String absoluteLink(ResourceResolver resolver,
                               String scheme,
                               String path)

Deprecated. since 5.5, use externalLink(resolver, Externalizer.LOCAL, scheme, path) instead

Externalizes the given resource path as an absolute URL. The hostname (and port) are taken from the resource resolver mapping configuration, if present, or from the service configuration. The context path will always be taken from the service configuration (the service implementation is free to use other mechanisms instead of configuration).

Parameters:

resolver - a resource resolver for retrieving the sling mapping configuration; can be null to rely solely on this service's configuration of host and context path

scheme - a protocol scheme such as "http", that will be part of the URL

path - a resource path; might contain extension, query or fragment, but plain paths are recommended; has to be without context path

Returns:

an absolute URL string

absoluteLink

@Deprecated
String absoluteLink(String scheme,
                               String path)

Deprecated. since 5.5, use externalLink(null, Externalizer.LOCAL, scheme, path) instead

Externalizes the given resource path as an absolute URL. The hostname (and port) as well as the context path are taken from the service configuration (the service implementation is free to use other mechanisms instead of configuration).

Parameters:

scheme - a protocol scheme such as "http", that will be part of the URL

path - a resource path; might contain extension, query or fragment, but plain paths are recommended; has to be without context path

Returns:

an absolute URL string