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

[kw...@apache.org]

Author: kwin
Date: Sat Nov 26 11:34:31 2016
New Revision: 1771466

URL: http://svn.apache.org/viewvc?rev=1771466&view=rev
Log:
SLING-6249 clarify how the servlet registration works

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=1771466&r1=1771465&r2=1771466&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/the-sling-engine/servlets.mdtext (original)
+++ sling/site/trunk/content/documentation/the-sling-engine/servlets.mdtext Sat Nov 26 11:34:31 2016
@@ -7,20 +7,21 @@ to a script or and servlet.
 
 ## Servlet Registration
 
-Servlets can be registered as OSGi services. The following service reference properties are defined for Servlets defined as OSGi services of type `javax.servlet.Servlet`:
+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)):
 
 | 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.<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.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. This property is ignored if the `sling.servlet.paths` property is set. |
-| `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 ignored if the `sling.servlet.paths` property is set. |
-| `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 ignored if the `sling.servlet.paths` property is set. |
-| `sling.servlet.methods` | The request methods supported by the servlet. The property value must either be a single String, an array of Strings or a Vector of Strings. This property is ignored if the `sling.servlet.paths` property is set. If this property is missing, the value defaults to GET, regardless of which methods are actually implemented/handled by the servlet.|
+| `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.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`. |
+| `sling.servlet.methods` | The request methods supported by the servlet. 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`. If this property is missing, the value defaults to GET and HEAD, regardless of which methods are actually implemented/handled by the servlet.|
 | `sling.servlet.prefix` | The prefix or numeric index to make relative paths absolute. If the value of this property is a number (int), it defines the index of the search path entries from the resource resolver to be used as the prefix. The defined search path is used as a prefix to mount this servlet. The number can be -1 which always points to the last search entry. If the specified value is higher than than the highest index of the search paths, the last entry is used. The index starts with 0. If the value of this property is a string and parseable as a number, the value is treated as if it would be a number. If the value of this property is a string starting with "/", this value is applied as a prefix, regardless of the configured search paths! If the value is anything else, it is ignored. If this property is not specified, it defaults to the default configuration of the sling servlet resolver. |
 
-A `SlingServletResolver` listens for `Servlet{`}services and - given the correct service registration properties - provides the servlets as resources in the (virtual) resource tree. Such servlets are provided as `ServletResource` instances which adapt to the `javax.servlet.Servlet` class.
+A `SlingServletResolver` listens for `Servlet` services and - given the correct service registration properties - provides the servlets as resources in the (virtual) resource tree. Such servlets are provided as `ServletResource` instances which adapt to the `javax.servlet.Servlet` class.
 
-For a Servlet registered as an OSGi service to be used by the Sling Servlet Resolver, either 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.
+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.
 
@@ -79,10 +80,9 @@ Such tests run as part of our continuous
 
 ### Example: Registration by Path
 
-    sling.servlet.paths = \[ "/libs/sling/sample/html", "/libs/sling/sample/txt" \]
-    sling.servlet.resourceTypes = \[ "sling/unused" \]
-    sling.servlet.selectors = \[ "img" \]
-    sling.servlet.extensions = \[ "html", "txt", "json" \]
+    sling.servlet.paths = [ "/libs/sling/sample/html", "/libs/sling/sample/txt" ]
+    sling.servlet.selectors = [ "img" ]
+    sling.servlet.extensions = [ "html", "txt", "json" ]
 
 
 A Servlet service registered with these properties is registered under the following paths:
@@ -90,27 +90,29 @@ A Servlet service registered with these
 * `/libs/sling/sample/html`
 * `/libs/sling/sample/txt`
 
-The registration properties `sling.servlet.resourceTypes`, `sling.servlet.selectors` and `sling.servlet.extensions` *are ignored* because the `sling.servlet.paths` property is set.
+The registration properties `sling.servlet.selectors` and `sling.servlet.extensions` *are ignored* because the servlet is registered only by path (only `sling.servlet.paths` property is set).
 
 
 ### Example: Registration by Resource Type etc.
 
 
-    sling.servlet.resourceTypes = \[ "sling/unused" \]
-    sling.servlet.selectors = \[ "img", "tab" \]
-    sling.servlet.extensions = \[ "html", "txt", "json" \]
+    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.
 
-A Servlet service registered with these properties is registered under the following paths:
-
-* `{*}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 For an explanation of 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 in the end registered (and by which
+other paths it might get overwritten).
 
 
 ### Servlet Lifecycle Issues
@@ -171,4 +173,4 @@ While an opting servlet seems to be a ni
 
 ## Error Handler Servlet(s) or Scripts
 
-Error handling support is now described on the [Errorhandling]({{ refs.errorhandling.path }}) page.
\ No newline at end of file
+Error handling support is described on the [Errorhandling]({{ refs.errorhandling.path }}) page.
\ No newline at end of file