svn commit: r1788209 - /sling/site/trunk/content/documentation/the-sling-engine/servlets.mdtext

[ro...@apache.org]

Author: rombert
Date: Thu Mar 23 09:29:18 2017
New Revision: 1788209

URL: http://svn.apache.org/viewvc?rev=1788209&view=rev
Log:
SLING-6699 - Clearly describe drawbacks of mounting servlets by path

Modified:
    sling/site/trunk/content/documentation/the-sling-engine/servlets.mdtext

Modified: sling/site/trunk/content/documentation/the-sling-engine/servlets.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/the-sling-engine/servlets.mdtext?rev=1788209&r1=1788208&r2=1788209&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/the-sling-engine/servlets.mdtext (original)
+++ sling/site/trunk/content/documentation/the-sling-engine/servlets.mdtext Thu Mar 23 09:29:18 2017
@@ -11,7 +11,7 @@ Servlets can be registered as OSGi servi
 
 | Name | Description |
 |--|--|
-| `sling.servlet.paths` | A list of absolute paths under which the servlet is accessible as a Resource. The property value must either be a single String, an array of Strings or a Vector of Strings.<br>A servlet using this property might be ignored unless its path is included in the *Execution Paths* (`servletresolver.paths`) configuration setting of the `SlingServletResolver` service. Either this property or the `sling.servlet.resourceTypes` property must be set, or the servlet is ignored. If both are set, the servlet is registered using both ways.<br>Creating a resource at the desired path, with a resource type that maps to a servlet, provides the same result in most cases while taking advantage of more Sling built-in features.|
+| `sling.servlet.paths` | A list of absolute paths under which the servlet is accessible as a Resource. The property value must either be a single String, an array of Strings or a Vector of Strings.<br>A servlet using this property might be ignored unless its path is included in the *Execution Paths* (`servletresolver.paths`) configuration setting of the `SlingServletResolver` service. Either this property or the `sling.servlet.resourceTypes` property must be set, or the servlet is ignored. If both are set, the servlet is registered using both ways.<br>Binding resources by paths is discouraged, see [caveats when binding servlets by path](#caveats-when-binding-servlets-by-path] below. |
 | `sling.servlet.resourceTypes` | The resource type(s) supported by the servlet. The property value must either be a single String, an array of Strings or a Vector of Strings. Either this property or the `sling.servlet.paths` property must be set, or the servlet is ignored. If both are set, the servlet is registered using both ways. |
 | `sling.servlet.selectors` | The request URL selectors supported by the servlet. The selectors must be configured as they would be specified in the URL that is as a list of dot-separated strings such as <em>print.a4</em>. The property value must either be a single String, an array of Strings or a Vector of Strings. This property is only considered for the registration with `sling.servlet.resourceTypes`. |
 | `sling.servlet.extensions` | The request URL extensions supported by the servlet for requests. The property value must either be a single String, an array of Strings or a Vector of Strings. This property is only considered for the registration with `sling.servlet.resourceTypes`. |
@@ -26,6 +26,17 @@ Each path to be used for registration -
 
 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.
 
+### Caveats when binding servlets by paths
+
+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. 
+
 #### Registering a Servlet using Java Annotations
 
 If you are working with the default Apache Sling development stack you can either use