Author: buildbot
Date: Sat Nov 26 11:38:17 2016
New Revision: 1001671
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 Sat Nov 26 11:38:17 2016
@@ -1 +1 @@
-1771435
+1771466
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
Sat Nov 26 11:38:17 2016
@@ -133,7 +133,7 @@ h2:hover > .headerlink, h3:hover > .head
<p>See also <a
href="/documentation/the-sling-engine/url-to-script-resolution.html">URL to
Script Resolution</a> which explains how Sling maps URLs
to a script or and servlet.</p>
<h2 id="servlet-registration">Servlet Registration<a class="headerlink"
href="#servlet-registration" title="Permanent link">¶</a></h2>
-<p>Servlets can be registered as OSGi services. The following service
reference properties are defined for Servlets defined as OSGi services of type
<code>javax.servlet.Servlet</code>:</p>
+<p>Servlets can be registered as OSGi services. The following service
reference properties are evaluated for Servlets defined as OSGi services of
type <code>javax.servlet.Servlet</code> (all those property names are defined
in <code>org.apache.sling.api.servlets.ServletResolverConstants</code> (since
API 2.15.2) or
<code>org.apache.sling.servlets.resolver.internal.ServletResolverConstants</code>
(before API 2.15.2)):</p>
<table class="table">
<thead>
<tr>
@@ -144,23 +144,27 @@ 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.<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.</td>
+</tr>
+<tr>
+<td><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></td>
</tr>
<tr>
<td><code>sling.servlet.resourceTypes</code></td>
-<td>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 <code>sling.servlet.paths</code> property is
set.</td>
+<td>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 <code>sling.servlet.paths</code> property must be set, or
the servlet is ignored. If both are set, the servlet is registered using both
ways.</td>
</tr>
<tr>
<td><code>sling.servlet.selectors</code></td>
-<td>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 <code>sling.servlet.paths</code> property is set.</td>
+<td>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
<code>sling.servlet.resourceTypes</code>.</td>
</tr>
<tr>
<td><code>sling.servlet.extensions</code></td>
-<td>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 <code>sling.servlet.paths</code>
property is set.</td>
+<td>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
<code>sling.servlet.resourceTypes</code>.</td>
</tr>
<tr>
<td><code>sling.servlet.methods</code></td>
-<td>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 <code>sling.servlet.paths</code> property is set. If
this property is missing, the value defaults to GET, regardless of which
methods are actually implemented/handled by the servlet.</td>
+<td>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
<code>sling.servlet.resourceTypes</code>. If this property is missing, the
value defaults to GET and HEAD, regardless of which methods are actually
implemented/handled by the servlet.</td>
</tr>
<tr>
<td><code>sling.servlet.prefix</code></td>
@@ -168,8 +172,8 @@ to a script or and servlet.</p>
</tr>
</tbody>
</table>
-<p>A <code>SlingServletResolver</code> listens for
<code>Servlet{</code>}services and - given the correct service registration
properties - provides the servlets as resources in the (virtual) resource tree.
Such servlets are provided as <code>ServletResource</code> instances which
adapt to the <code>javax.servlet.Servlet</code> class.</p>
-<p>For a Servlet registered as an OSGi service to be used by the Sling Servlet
Resolver, either 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>A <code>SlingServletResolver</code> listens for <code>Servlet</code>
services and - given the correct service registration properties - provides the
servlets as resources in the (virtual) resource tree. Such servlets are
provided as <code>ServletResource</code> instances which adapt to the
<code>javax.servlet.Servlet</code> class.</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 requests. Make sure to list all methods you want to
be handled by this servlet.</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">¶</a></h4>
@@ -222,10 +226,9 @@ servlets and describe their binding deta
<p>The <a
href="http://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests/";>launchpad/integration-tests</a>
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.</p>
<p>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!</p>
<h3 id="example-registration-by-path">Example: Registration by Path<a
class="headerlink" href="#example-registration-by-path" title="Permanent
link">¶</a></h3>
-<div class="codehilite"><pre><span class="n">sling</span><span
class="p">.</span><span class="n">servlet</span><span class="p">.</span><span
class="n">paths</span> <span class="p">=</span> <span class="o">\</span><span
class="p">[</span> "<span class="o">/</span><span
class="n">libs</span><span class="o">/</span><span class="n">sling</span><span
class="o">/</span><span class="n">sample</span><span class="o">/</span><span
class="n">html</span>"<span class="p">,</span> "<span
class="o">/</span><span class="n">libs</span><span class="o">/</span><span
class="n">sling</span><span class="o">/</span><span
class="n">sample</span><span class="o">/</span><span class="n">txt</span>"
<span class="o">\</span><span class="p">]</span>
-<span class="n">sling</span><span class="p">.</span><span
class="n">servlet</span><span class="p">.</span><span
class="n">resourceTypes</span> <span class="p">=</span> <span
class="o">\</span><span class="p">[</span> "<span
class="n">sling</span><span class="o">/</span><span
class="n">unused</span>" <span class="o">\</span><span class="p">]</span>
-<span class="n">sling</span><span class="p">.</span><span
class="n">servlet</span><span class="p">.</span><span
class="n">selectors</span> <span class="p">=</span> <span
class="o">\</span><span class="p">[</span> "<span
class="n">img</span>" <span class="o">\</span><span class="p">]</span>
-<span class="n">sling</span><span class="p">.</span><span
class="n">servlet</span><span class="p">.</span><span
class="n">extensions</span> <span class="p">=</span> <span
class="o">\</span><span class="p">[</span> "<span
class="n">html</span>"<span class="p">,</span> "<span
class="n">txt</span>"<span class="p">,</span> "<span
class="n">json</span>" <span class="o">\</span><span class="p">]</span>
+<div class="codehilite"><pre><span class="n">sling</span><span
class="p">.</span><span class="n">servlet</span><span class="p">.</span><span
class="n">paths</span> <span class="p">=</span> <span class="p">[</span>
"<span class="o">/</span><span class="n">libs</span><span
class="o">/</span><span class="n">sling</span><span class="o">/</span><span
class="n">sample</span><span class="o">/</span><span
class="n">html</span>"<span class="p">,</span> "<span
class="o">/</span><span class="n">libs</span><span class="o">/</span><span
class="n">sling</span><span class="o">/</span><span
class="n">sample</span><span class="o">/</span><span class="n">txt</span>"
<span class="p">]</span>
+<span class="n">sling</span><span class="p">.</span><span
class="n">servlet</span><span class="p">.</span><span
class="n">selectors</span> <span class="p">=</span> <span class="p">[</span>
"<span class="n">img</span>" <span class="p">]</span>
+<span class="n">sling</span><span class="p">.</span><span
class="n">servlet</span><span class="p">.</span><span
class="n">extensions</span> <span class="p">=</span> <span class="p">[</span>
"<span class="n">html</span>"<span class="p">,</span> "<span
class="n">txt</span>"<span class="p">,</span> "<span
class="n">json</span>" <span class="p">]</span>
</pre></div>
@@ -234,24 +237,26 @@ servlets and describe their binding deta
<li><code>/libs/sling/sample/html</code></li>
<li><code>/libs/sling/sample/txt</code></li>
</ul>
-<p>The registration properties <code>sling.servlet.resourceTypes</code>,
<code>sling.servlet.selectors</code> and <code>sling.servlet.extensions</code>
<em>are ignored</em> because the <code>sling.servlet.paths</code> property is
set.</p>
+<p>The registration properties <code>sling.servlet.selectors</code> and
<code>sling.servlet.extensions</code> <em>are ignored</em> because the servlet
is registered only by path (only <code>sling.servlet.paths</code> property is
set).</p>
<h3 id="example-registration-by-resource-type-etc">Example: Registration by
Resource Type etc.<a class="headerlink"
href="#example-registration-by-resource-type-etc" title="Permanent
link">¶</a></h3>
-<div class="codehilite"><pre><span class="n">sling</span><span
class="p">.</span><span class="n">servlet</span><span class="p">.</span><span
class="n">resourceTypes</span> <span class="p">=</span> <span
class="o">\</span><span class="p">[</span> "<span
class="n">sling</span><span class="o">/</span><span
class="n">unused</span>" <span class="o">\</span><span class="p">]</span>
-<span class="n">sling</span><span class="p">.</span><span
class="n">servlet</span><span class="p">.</span><span
class="n">selectors</span> <span class="p">=</span> <span
class="o">\</span><span class="p">[</span> "<span
class="n">img</span>"<span class="p">,</span> "<span
class="n">tab</span>" <span class="o">\</span><span class="p">]</span>
-<span class="n">sling</span><span class="p">.</span><span
class="n">servlet</span><span class="p">.</span><span
class="n">extensions</span> <span class="p">=</span> <span
class="o">\</span><span class="p">[</span> "<span
class="n">html</span>"<span class="p">,</span> "<span
class="n">txt</span>"<span class="p">,</span> "<span
class="n">json</span>" <span class="o">\</span><span class="p">]</span>
+<div class="codehilite"><pre><span class="n">sling</span><span
class="p">.</span><span class="n">servlet</span><span class="p">.</span><span
class="n">resourceTypes</span> <span class="p">=</span> <span
class="p">[</span> "<span class="n">sling</span><span
class="o">/</span><span class="n">unused</span>" <span class="p">]</span>
+<span class="n">sling</span><span class="p">.</span><span
class="n">servlet</span><span class="p">.</span><span
class="n">selectors</span> <span class="p">=</span> <span class="p">[</span>
"<span class="n">img</span>"<span class="p">,</span> "<span
class="n">tab</span>" <span class="o">\</span><span class="p">]</span>
+<span class="n">sling</span><span class="p">.</span><span
class="n">servlet</span><span class="p">.</span><span
class="n">extensions</span> <span class="p">=</span> <span class="p">[</span>
"<span class="n">html</span>"<span class="p">,</span> "<span
class="n">txt</span>"<span class="p">,</span> "<span
class="n">json</span>" <span class="p">]</span>
</pre></div>
-<p>A Servlet service registered with these properties is registered under the
following paths:</p>
+<p>A Servlet service registered with these properties is registered for the
following resource types:</p>
<ul>
-<li><code>{*}prefix*/sling/unused/img/html</code></li>
-<li><code>{*}prefix*/sling/unused/img/txt</code></li>
-<li><code>{*}prefix*/sling/unused/img/json</code></li>
-<li><code>{*}prefix*/sling/unused/tab/html</code></li>
-<li><code>{*}prefix*/sling/unused/tab/txt</code></li>
-<li><code>{*}prefix*/sling/unused/tab/json</code></li>
+<li><code><prefix>/sling/unused/img/html</code></li>
+<li><code><prefix>/sling/unused/img/txt</code></li>
+<li><code><prefix>/sling/unused/img/json</code></li>
+<li><code><prefix>/sling/unused/tab/html</code></li>
+<li><code><prefix>/sling/unused/tab/txt</code></li>
+<li><code><prefix>/sling/unused/tab/json</code></li>
</ul>
-<p>As explained the Servlet is registered for each permutation of the resource
types, selectors and extension. See above For an explanation of how
<code>{*}prefix{*</code>} is defined.</p>
+<p>As explained the Servlet is registered for each permutation of the resource
types, selectors and extension. See above at the explanation of
<code>sling.servlet.prefix</code> how <code><prefix></code> is
defined.</p>
+<p>It is more common to register for absolute resource types or at least
explicitly define <code>sling.servlet.prefix</code> 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).</p>
<h3 id="servlet-lifecycle-issues">Servlet Lifecycle Issues<a
class="headerlink" href="#servlet-lifecycle-issues" title="Permanent
link">¶</a></h3>
<p>The Servlet API specification states the following with respect to the life
cycle of Servlets:</p>
@@ -288,9 +293,9 @@ The mechanism helping the provider here
<p>In this case, the servlet is only selected for processing the current
request if its <code>accept</code> method returns true.</p>
<p>While an opting servlet seems to be a nice way of picking the right servlet
to process the request, the use of an opting servlet is not recommended: the
main reason is that it complicates the request processing, makes it less
transparent what is going on during a request and prevents optimizations like
caching the script resolution in an optimal manner. The other static options
are usually sufficient for all use cases.</p>
<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">¶</a></h2>
-<p>Error handling support is now described on the <a
href="/documentation/the-sling-engine/errorhandling.html">Errorhandling</a>
page.</p>
+<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. 1678488 by cziegeler on Sat, 9 May 2015 12:43:11 +0000
+ Rev. 1771466 by kwin on Sat, 26 Nov 2016 11:34:31 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache
Sling project
