incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fmesc...@apache.org
Subject svn commit: r1348706 - in /sling/site/trunk/content: documentation/the-sling-engine/servlets.mdtext res/site.css
Date Mon, 11 Jun 2012 01:55:58 GMT
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



Mime
View raw message