Package 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"

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 Details

    • 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:

    • AUTHOR

      static final String AUTHOR
      Name for domain configuration that contains the author DNS address. For example http://author.website.com.
      See Also:

    • PUBLISH

      static final String PUBLISH
      Name for domain configuration that contains the public website DNS address. For example http://www.website.com.
      See Also:

  • Method Details

    • 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:

    • 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

      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:

    • 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:

    • 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:

    • 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:

    • 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