svn commit: r1008844 - in /websites/staging/sling/trunk/content: ./ documentation/the-sling-engine/servlets.html

[bu...@apache.org]

Author: buildbot
Date: Thu Mar 23 09:29:37 2017
New Revision: 1008844

Log:
Staging update by buildbot for sling

Modified:
    websites/staging/sling/trunk/content/   (props changed)
    websites/staging/sling/trunk/content/documentation/the-sling-engine/servlets.html

Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Mar 23 09:29:37 2017
@@ -1 +1 @@
-1788163
+1788209

Modified: websites/staging/sling/trunk/content/documentation/the-sling-engine/servlets.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/servlets.html (original)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/servlets.html Thu Mar 23 09:29:37 2017
@@ -117,7 +117,10 @@ h2:hover > .headerlink, h3:hover > .head
 <div class="toc">
 <ul>
 <li><a href="#servlet-registration">Servlet Registration</a><ul>
+<li><a href="#caveats-when-binding-servlets-by-paths">Caveats when binding servlets by paths</a><ul>
 <li><a href="#registering-a-servlet-using-java-annotations">Registering a Servlet using Java Annotations</a></li>
+</ul>
+</li>
 <li><a href="#automated-tests">Automated tests</a></li>
 <li><a href="#example-registration-by-path">Example: Registration by Path</a></li>
 <li><a href="#example-registration-by-resource-type-etc">Example: Registration by Resource Type etc.</a></li>
@@ -144,7 +147,7 @@ to a script or and servlet.</p>
 <tbody>
 <tr>
 <td><code>sling.servlet.paths</code></td>
-<td>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 <em>Execution Paths</em> (<code>servletresolver.paths</code>) configuration setting of the <code>SlingServletResolver</code> service. Either this property or the <code>sling.servlet.resourceTypes</code> 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.</td>
+<td>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 <em>Execution Paths</em> (<code>servletresolver.paths</code>) configuration setting of the <code>SlingServletResolver</code> service. Either this property or the <code>sling.servlet.resourceTypes</code> 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.</td>
 </tr>
 <tr>
 <td><code>sling.servlet.resourceTypes</code></td>
@@ -172,6 +175,15 @@ to a script or and servlet.</p>
 <p>For a Servlet registered as an OSGi service to be used by the Sling Servlet Resolver, either one or both of the <code>sling.servlet.paths</code> or the <code>sling.servlet.resourceTypes</code> service reference properties must be set. If neither is set, the Servlet service is ignored.</p>
 <p>Each path to be used for registration - either from the <code>sling.servlet.paths</code> property or constructed from the other <code>sling.servlet.\*</code> properties - must be absolute. Any relative path is made absolute by prefixing it with a root path. This prefix may be set with the <code>sling.servlet.prefix</code> service registration property. If this property is not set, the first entry in the <code>ResourceResolver</code> search path for the <code>ResourceResolver.getResource(String)</code> method is used as the prefix. If this entry cannot be derived, a simpe slash - <code>/</code> - is used as the prefix.</p>
 <p>If <code>sling.servlet.methods</code> 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.</p>
+<h3 id="caveats-when-binding-servlets-by-paths">Caveats when binding servlets by paths<a class="headerlink" href="#caveats-when-binding-servlets-by-paths" title="Permanent link">&para;</a></h3>
+<p>Binding servlets by paths has several disadvantages when compared to binding by resource types, namely:</p>
+<ul>
+<li>path-bound servlets cannot be access controlled using the default JCR repository ACLs</li>
+<li>path-bound servlets can only be registered to a path and not a resource type (i.e. no suffix handling)</li>
+<li>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</li>
+<li>the mapping is not transparent to a developer looking just at the repository</li>
+</ul>
+<p>Given these drawbacks it is strongly recommended to bind servlets to resource types rather than paths. </p>
 <h4 id="registering-a-servlet-using-java-annotations">Registering a Servlet using Java Annotations<a class="headerlink" href="#registering-a-servlet-using-java-annotations" title="Permanent link">&para;</a></h4>
 <p>If you are working with the default Apache Sling development stack you can either use </p>
 <ul>
@@ -296,7 +308,7 @@ The mechanism helping the provider here
 <h2 id="error-handler-servlets-or-scripts">Error Handler Servlet(s) or Scripts<a class="headerlink" href="#error-handler-servlets-or-scripts" title="Permanent link">&para;</a></h2>
 <p>Error handling support is described on the <a href="/documentation/the-sling-engine/errorhandling.html">Errorhandling</a> page.</p>
       <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
-        Rev. 1771573 by kwin on Sun, 27 Nov 2016 11:58:27 +0000
+        Rev. 1788209 by rombert on Thu, 23 Mar 2017 09:29:18 +0000
       </div>
       <div class="trademarkFooter"> 
         Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project