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
