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"

    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 Detail

      • LOCAL

        static final java.lang.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 java.lang.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 java.lang.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

        java.lang.String externalLink​(ResourceResolver resolver,
                              java.lang.String domain,
                              java.lang.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

        java.lang.String externalLink​(ResourceResolver resolver,
                              java.lang.String domain,
                              java.lang.String scheme,
                              java.lang.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

        java.lang.String publishLink​(ResourceResolver resolver,
                             java.lang.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

        java.lang.String publishLink​(ResourceResolver resolver,
                             java.lang.String scheme,
                             java.lang.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

        java.lang.String authorLink​(ResourceResolver resolver,
                            java.lang.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

        java.lang.String authorLink​(ResourceResolver resolver,
                            java.lang.String scheme,
                            java.lang.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

        java.lang.String relativeLink​(SlingHttpServletRequest request,
                              java.lang.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

        java.lang.String absoluteLink​(SlingHttpServletRequest request,
                              java.lang.String scheme,
                              java.lang.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
java.lang.String absoluteLink​(ResourceResolver resolver,
                              java.lang.String scheme,
                              java.lang.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
java.lang.String absoluteLink​(java.lang.String scheme,
                              java.lang.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