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
