Author: fmeschbe
Date: Mon Jun 11 01:55:58 2012
New Revision: 1348706
URL: http://svn.apache.org/viewvc?rev=1348706&view=rev
Log:
SLING-2002 Add section on Servlet Lifecycle
- plus some small layout fixes
- plus blockquote style
Modified:
sling/site/trunk/content/documentation/the-sling-engine/servlets.mdtext
sling/site/trunk/content/res/site.css
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=1348706&r1=1348705&r2=1348706&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/the-sling-engine/servlets.mdtext
(original)
+++ sling/site/trunk/content/documentation/the-sling-engine/servlets.mdtext Mon
Jun 11 01:55:58 2012
@@ -1,12 +1,14 @@
Title: Servlets and Scripts
+[TOC]
+
+## 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`:
| 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.
-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.
-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.<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. |
@@ -22,14 +24,15 @@ Each path to be used for registration -
If `sling.servlet.methods` is not specified, the servlet is only registered
for handling GET requests. Make sure to list all methods you want to be handled
by this servlet.
### Automated tests
+
The [launchpad/test-services]({{
refs.http://svn.apache.org/repos/asf/sling/trunk/launchpad/test-services/.path
}}) module contains test servlets that use various combinations of the above
properties.
The [launchpad/integration-tests]({{
refs.http://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests/.path
}}) module contains a number of tests (like the
[ExtensionServletTest|http://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/servlets/resolution/ExtensionServletTest.java]
for example) that verify the results.
Such tests run as part of our continuous integration process, to demonstrate
and verify the behavior of the various servlet registration mechanisms, in a
way that's guaranteed to be in sync with the actual Sling core code. If you
have an idea for additional tests, make sure to let us know!
-### Example: Registration by Path
+### Example: Registration by Path
sling.servlet.paths = \[ "/libs/sling/sample/html",
"/libs/sling/sample/txt" \]
sling.servlet.resourceTypes = \[ "sling/unused" \]
@@ -65,6 +68,30 @@ A Servlet service registered with these
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.
+### Servlet Lifecycle Issues
+
+The Servlet API specification states the following with respect to the life
+cycle of Servlets:
+
+> The servlet container calls the init method exactly once after
+> instantiating the servlet.
+
+This works perfectly in a regular servlet container which both instantiates
+and initializes the servlets. With Sling the tasks of instantiation and
+initialization are split:
+
+* The provider of the Servlet service takes care of creating the servlet
instance
+* The Sling Servlet Resolver picks up the Servlet services and initializes and
destroys them as needed
+
+So Sling has not way of making sure a Servlet is only initialized and destroyed
+once in the life time of the Servlet object instance.
+
+The provider of the Servlet service on the other can cope with this
+situation by making sure to drop the servlet instance once it is destroyed.
+The mechanism helping the provider here is the OSGi Service Factory.
+
+
+
## Scripts are Servlets
@@ -75,8 +102,6 @@ To further simplify the access to script
From the perspective of the Servlet resolver, scripts and servlets are handled
exactly the same. In fact, internally, Sling only handles with Servlets,
whereas scripts are packed inside a Servlet wrapping and representing the
script.
-##
-
## Default Servlet(s)
@@ -89,7 +114,9 @@ Finally, if not even a registered defaul
* If an `NonExistingResource` was created for the request the `DefaultServlet`
sends a 404 (Not Found)
* Otherwise the `DefaultServlet` sends a 500 (Internal Server Error), because
normally at least a `NonExistingResource` should be created
+
## OptingServlet interface
+
If a registered servlet implements the OptingServlet interface, Sling uses
that servlet's `accepts(SlingHttpServletRequest request)` method to refine the
servlet resolution process.
In this case, the servlet is only selected for processing the current request
if its `accept` method returns true.
Modified: sling/site/trunk/content/res/site.css
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/res/site.css?rev=1348706&r1=1348705&r2=1348706&view=diff
==============================================================================
--- sling/site/trunk/content/res/site.css (original)
+++ sling/site/trunk/content/res/site.css Mon Jun 11 01:55:58 2012
@@ -212,5 +212,9 @@ td {
text-align: left;
}
-/* Code High Lighting */
-
+blockquote {
+ font-style: italic;
+ margin: 0;
+ padding-left: 1em;
+ border-left: 1px solid black;
+}
\ No newline at end of file
