Home » Documentation » The Sling Engine

URL to Script Resolution

This page explains how Sling maps URLs to a script or and servlet.

See also Servlets and Scripts which provides detailed info about how to register servlets.

First of all Sling looks up the resource identified by the URL - typically a path inside the JCR repository, which is annotated by the sling:resourceType property which defines the resource type of that resource. Using this resource type (which is kind of a relative path, eg. "myblog/comment"), scripts or servlets are looked up. For more details about how the initial resource is identified for a specific request URL look at URL decomposition.

Scripts and servlets are itself resources in Sling and thus have a resource path: this is either the location in the JCR repository, the resource type in a servlet component configuration or the "virtual" bundle resource path (if a script is provided inside a bundle without being installed into the JCR repository).

For the whole Truth about script resolution, see the ScriptSelectionTest class. If you see interesting cases that are not covered there, please let us know via the Sling users mailing list.

TODO: explain super types, servlet path mappings, node type resource types (my:type -> my/type)

Fundamental: Scripts and Servlets are equal

In the following discussion, I will write about scripts. This will always include servlets as well. In fact, internally, Sling only handles with Servlets, whereas scripts are packed inside a Servlet wrapping and representing the script.

Base: Resource Type Inheritance

While not exactly part of our discussion, resource type inheritance as implemented for SLING-278 plays a vital role in script resolution.

Each resource type may have a resource super type, which may be defined in various ways. One example is having a sling:resourceSuperType property in the node addressed by the resource type. See http://www.mail-archive.com/sling-dev@incubator.apache.org/msg02365.html and SLING-278 for more details.

If a resource type has no explicit resource super type, the resource super type is assumed to be "sling/servlet/default". That is the resource type used for default script selection is also acting as a basic resource type much like java.lang.Object does for other types in the Java language.

Script Locations

Scripts are looked up in a series of locations defined by the ResourceResolver.getSearchPath() and the resource type (and resource super types) of the requested resource:


The pseudo code for iterating the locations would be something like:

var type = resource.getResourceType(); 
while (type != null) { 
    for (String root: resourceResolver.getSearchPath()) { 
        String path = root + type.toPath(); 

    if (type == defaultServlet) { 
        type = null; 
    } else { 
        type = getResourceSuperType(type); 
        if (type == null) { 
            type = defaultServlet; 

All requests are NOT equal

GET and HEAD request methods are treated differently than the other request methods. Only for GET and HEAD requests will the request selectors and extension be considered for script selection. For other requests the servlet or script name (without the script extension) must exactly match the request method.

That is for a PUT request, the script must be PUT.esp or PUT.jsp. For a GET request with a request extension of html, the script name may be html.esp or GET.esp.

Scripts for GET requests

Apart for supporting scripts named after the request method, scripts handling GET and HEAD requests may be named differently for Sling to support a more elaborate processing order.

Depending on whether request selectors are considered, a script may have two forms:

The constituents of these script names are as follows:


The rules for script path priorization is defined as follows:


Let's consider the following script paths for a request of a resource whose resource type is sling\sample and the request selectors are print.a4 and the request extension is html:

The priority of script selection would be (starting with the best one): (6) - (4) - (5) - (3) - (2) - (1) - (0). Note that (4) is a better match than (5) because it matches more selectors even though (5) has an extension match where (4) does not. (7) is not a candidate because it does not include the first selector (print) and (8) is not a candidate because it has the wrong order of selectors.

Rev. 1761920 by kwin on Thu, 22 Sep 2016 12:10:40 +0000
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.