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