Servlets and Scripts

Servlet Resolving

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 usually a relative resource path, eg. "myblog/comment"), servlets (or scripts) are looked up. For more details about how the initial resource is identified for a specific request URL look at URL decomposition.

Servlets and scripts are themselves resources in Sling and thus have a resource path: this is either the location in the resource 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 details on which script/servlet is selected in case there are multiple candidates refer to the sections below.

Servlet Registration

Servlets can be registered as OSGi services. The following service reference properties are evaluated for Servlets defined as OSGi services of type javax.servlet.Servlet (all those property names are defined in org.apache.sling.api.servlets.ServletResolverConstants (since API 2.15.2) or org.apache.sling.servlets.resolver.internal.ServletResolverConstants (before API 2.15.2):

For a Servlet registered as an OSGi service to be used by the Sling Servlet Resolver, either one or both of the sling.servlet.paths or the sling.servlet.resourceTypes service reference properties must be set. If neither is set, the Servlet service is ignored.

Each path to be used for registration - either from the sling.servlet.paths property or constructed from the other sling.servlet.* properties - must be absolute. Any relative path is made absolute by prefixing it with a root path. This prefix may be set with the sling.servlet.prefix service registration property. If this property is not set, the first entry in the ResourceResolver search path for the ResourceResolver.getResource(String) method is used as the prefix. If this entry cannot be derived, a simpe slash - / - is used as the prefix.

If sling.servlet.methods is not specified, the servlet is only registered for handling GET and HEAD requests. Make sure to list all methods you want to be handled by this servlet.

Servlet Resource Provider

A ServletMounter listens for javax.servlet.Servlet services. This only applies to OSGi services implementing javax.servlet.Servlet. Each individual servlet will have a dedicated service instance of ServletResourceProvider associated to it, which will provide ServletResources in the resource tree, based on the servlet's registration properties. The actual resource path of such resources differs for servlets registered by type and those registered by path:

If multiple servlets are registered for the same metadata the one with the highest service ranking is returned in the virtual resource tree. The resources expose the following properties:

In addition each such resource can be adapted to a Servlet.

Caveats when binding servlets by path

Binding servlets by paths has several disadvantages when compared to binding by resource types, namely:

• path-bound servlets cannot be access controlled using the default JCR repository ACLs
• path-bound servlets can only be registered to a path and not a resource type (i.e. no suffix handling)
• if a path-bound servlet is not active, e.g. if the bundle is missing or not started, a POST might result in unexpected results. usually creating a node at /bin/xyz which subsequently overlays the servlets path binding
• the mapping is not transparent to a developer looking just at the repository

Given these drawbacks it is strongly recommended to bind servlets to resource types rather than paths.

The sling.servlet.paths.strict mode described on this page slightly improves things by enabling a stricter selection of path-bound servlets, but that's only minor improvements.

Registering a Servlet using Java Annotations

The "new" (as of 2018) Sling Servlet annotations were presented by Konrad Windszus at adaptTo() 2018.

If you are working with the default Apache Sling development stack you can either use

• OSGi DS 1.4 (R7) component property type annotations (introduced with DS 1.4/OSGi R7, supported since bnd 4.1 being used in bnd-maven-plugin 4.1.0+ and maven-bundle-plugin 4.1.0+),
• OSGi DS annotations (introduced with DS 1.2/OSGi R5, properly supported since bnd 3.0, being used in maven-bundle-plugin 3.0.0) or
• Generic Felix SCR or Sling-specific @SlingServlet annotations from Apache Felix Maven SCR Plugin to register your Sling servlets:

The following examples show example code how you can register Servlets with Sling

1. OSGi DS 1.4 (R7) component property type annotations for Sling Servlets (recommended)

   @Component(service = { Servlet.class })
   @SlingServletResourceTypes(
       resourceTypes="/apps/my/type", 
       methods= "GET",
       extensions="html",
       selectors="hello")
   public class MyServlet extends SlingSafeMethodsServlet {
   
       @Override
       protected void doGet(SlingHttpServletRequest request, SlingHttpServletResponse response) throws ServletException, IOException {
           ...
       }
   }
   

   This is only supported though if you use either the bnd-maven-plugin or the maven-bundle-plugin in version 4.0.0 or newer and use Sling which is at least compliant with OSGi R6 (DS 1.3). There is no actual run-time dependency to OSGi R7! The configuration for the bnd-maven-plugin should look like this in your pom.xml

   <build>
     ...
     <plugins>
       <plugin>
         <groupId>biz.aQute.bnd</groupId>
         <artifactId>bnd-maven-plugin</artifactId>
         <version>4.0.0</version>
         <executions>
           <execution>
             <goals>
               <goal>bnd-process</goal>
             </goals>
           </execution>
         </executions>
       </plugin>
       ...
     </plugins>
     ...
   </build>
   ...
   <dependencies>
     ...
     <!-- dependency towards the custom component property type annotations for Sling Servlets -->
     <dependency>
       <groupId>org.apache.sling</groupId>
       <artifactId>org.apache.sling.servlets.annotations</artifactId>
       <version>1.2.4</version>
     </dependency>
     ...
   </dependencies>
   

   Please refer to the Javadoc of the package for other related annotations.

   Starting with version 1.2.4 of the org.apache.sling.servlets.annotations you can also generate a value for the sling.servlet.resourceSuperType registration property, by using the resourceSuperType annotation property (its default value is sling/bundle/resource). In order for the property to be taken into consideration, your Sling instance has to provide version 2.5.2 or newer of the org.apache.sling.servlets.resolver bundle.

2. Simple OSGi DS 1.2 annotations (use only if you cannot use approach 1.)

   @Component(
   service = { Servlet.class },
   property = { 
       SLING_SERVLET_RESOURCE_TYPES + "=/apps/my/type"
       SLING_SERVLET_METHODS + "=GET",
       SLING_SERVLET_EXTENSIONS + "=html",
       SLING_SERVLET_SELECTORS + "=hello",
     }
   )
   public class MyServlet extends SlingSafeMethodsServlet {
   
       @Override
       protected void doGet(SlingHttpServletRequest request, SlingHttpServletResponse response) throws ServletException, IOException {
           ...
       }
   }
   

3. The @SlingServlet annotation (evaluated by maven-scr-plugin, use only if you can neither use 1. nor 2.)

   @SlingServlet(
       resourceTypes = "/apps/my/type",
       selectors = "hello",
       extensions = "html",
       methods = "GET")
   public class MyServlet extends SlingSafeMethodsServlet {
   
       @Override
       protected void doGet(SlingHttpServletRequest request, SlingHttpServletResponse response) throws ServletException, IOException {
           ...
       }
   }
   

Automated tests

The launchpad/test-services module contains test servlets that use various combinations of the above properties.

The launchpad/integration-tests module contains a number of tests (like the [ExtensionServletTest|https://github.com/apache/sling-org-apache-sling-launchpad-integration-tests/blob/master/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/servlets/resolution/ExtensionServletTest.java] for example) that verify the results.

The sling-org-apache-sling-servlets-resolver module also has some tests which provide more specific information about these mechanisms.

Such tests run as part of our continuous integration process, to demonstrate and verify the behavior of the various servlet registration mechanisms, in a way that's guaranteed to be in sync with the actual Sling core code. If you have an idea for additional tests, patches are welcome!

Example: Registration by Path

The sling.servlet.paths.strict mode described in the next example is preferred over this older way of mounting servlets by path, where a Servlet service with these properties:

sling.servlet.paths = [ "/libs/sling/sample/html", "/libs/sling/sample/txt" ]

Is registered under the indicated paths, without requiring Resources to be present under those paths.

Other sling.servlet.* service properties such are ignored in this mode. To take them into account, use the sling.servlet.paths.strict mode described in the next example.

See also the caveats when binding servlets by path .

Example: Registration by Path, strict mode

This strict mode was added in version 2.6.6 of the org.apache.sling.servlets.resolver module and is preferred over the old mode where just the path is taken into account for path-mounted servlets.

sling.servlet.paths = [ "/libs/sling/sample/html", "/libs/sling/sample/txt" ]
sling.servlet.paths.strict = true
sling.servlet.selectors = [ ".EMPTY." ]
sling.servlet.extensions = [ "html", "txt", "json" ]
sling.servlet.methods = [ "GET" ]

The sling.servlet.paths.strict property has been added to allow stricter criteria for selecting path-mounted servlets.

In the above example, the servlet is mounted on the indicated paths, but only if the request has one of the indicated extensions, uses the GET method and has no selectors. See the above documentation of the sling.servlet.paths.strict property for more information, and see also the caveats when binding servlets by path .

Example: Registration by Resource Type etc.

sling.servlet.resourceTypes = [ "sling/unused" ]
sling.servlet.selectors = [ "img", "tab" ]
sling.servlet.extensions = [ "html", "txt", "json" ]

A Servlet service registered with these properties is registered for the following resource types:

• <prefix>/sling/unused/img/html
• <prefix>/sling/unused/img/txt
• <prefix>/sling/unused/img/json
• <prefix>/sling/unused/tab/html
• <prefix>/sling/unused/tab/txt
• <prefix>/sling/unused/tab/json

As explained the Servlet is registered for each permutation of the resource types, selectors and extension. See above at the explanation of sling.servlet.prefix how <prefix> is defined.

It is more common to register for absolute resource types or at least explicitly define sling.servlet.prefix as well, because otherwise you are in most cases not sure under which absolute path the Servlet is registered (and therefore by which other paths it might get overwritten).

Servlet Lifecycle Issues

The Servlet API specification states the following with respect to the life cycle of Servlets:

The servlet container calls the init method exactly once after instantiating the servlet.

This works perfectly in a regular servlet container which both instantiates and initializes the servlets. With Sling the tasks of instantiation and initialization are split:

• The provider of the Servlet service takes care of creating the servlet instance
• The Sling Servlet Resolver picks up the Servlet services and initializes and destroys them as needed

So Sling has not way of making sure a Servlet is only initialized and destroyed once in the life time of the Servlet object instance.

The provider of the Servlet service on the other can cope with this situation by making sure to drop the servlet instance once it is destroyed. The mechanism helping the provider here is the OSGi Service Factory.

Default Servlet(s)

As explained in the Resolution Process section above, a default Servlet is selected if no servlet (or script) for the current resource type can be found. To make the provisioning of a default Servlet as versatile as provisioning per resource type Servlets (or scripts), the default Servlet is selected with just a special resource type sling/servlet/default.

The actual Servlet or Script called as the default Servlet is resolved exactly the same way as for any resource type. That is, also for the default Servlet selection, the request selectors and extension or method are considered. Also, the Servlet may be a Servlet registered as an OSGi service or it may be a Script stored in the repository or provided by any bundle.

Finally, if not even a registered default Servlet may be resolved for the request, because none has been registered, the servlets/resolver bundle provides a fall back the DefaultServlet with the following functionality:

• If an NonExistingResource was created for the request the DefaultServlet sends a 404 (Not Found)
• Otherwise the DefaultServlet sends a 500 (Internal Server Error), because normally at least a NonExistingResource should be created

Scripts

Scripts are internally handled like servlet, details are described in Sling Scripting.

OptingServlet interface

If a registered servlet implements the OptingServlet interface, Sling uses that servlet's accepts(SlingHttpServletRequest request) method to refine the servlet resolution process.

In this case, the servlet is only selected for processing the current request if its accept method returns true.

While an opting servlet seems to be a nice way of picking the right servlet to process the request, the use of an opting servlet is not recommended: the main reason is that it complicates the request processing, makes it less transparent what is going on during a request and prevents optimizations like caching the script resolution in an optimal manner. The other static options are usually sufficient for all use cases.

Servlet Resolution Order

The following order rules are being followed when trying to resolve a servlet for a given request URL and request method and multiple candidates would match. Then the following candidate is being picked (if one rule doesn't lead to one winner, the next rule is being evaluated):

1. The one with the highest number of matching selectors + extension
2. The one which is registered to a resource type closest to the requested one (when traversing the resource type hierarchy up), refer to section Resource Type Inheritance for more details
3. The one with the highest service ranking according to OSGi Core 8 Chapter 5.2.6

In case of an OptingServlet not matching the next candidate is being used.

Resource Type Inheritance

Resource type inheritance as implemented for SLING-278 plays a vital role in servlet 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 resource addressed by the resource type. See http://www.mail-archive.com/sling-dev@incubator.apache.org/msg02365.html and SLING-278 for more details. Also the servlet (or script) itself may define a resource super type (which is only used in case the request resource does not define one).

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.

Error Handler Servlet(s) or Scripts

Error handling support is described on the Errorhandling page.

OSGi HTTP Whiteboard Servlets

For certain edge cases even in an OSGi runtime running Sling certain servlets are still registered leveraging the OSGi HTTP Whiteboard instead of leveraging the Sling servlet registration outlined above. Note though, that whenever the Sling engine bundle is deployed it registers a Servlet with the OSGi HTTP Whiteboard for path / which will take precedence by default over all other servlets registered through OSGi Http Whiteboard leveraging the default servlet context SLING-11677. Therefore, all servlets registered via OSGi HTTP Whiteboard need to be registered with a custom context having a service.ranking higher than the one from the Sling Main servlet (=0).