incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Sling Website > Servlets
Date Thu, 10 May 2012 19:11:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/1/_/styles/combined.css?spaceKey=SLINGxSITE&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/SLINGxSITE/Servlets">Servlets</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~bdelacretaz">Bertrand
Delacretaz</a>
    </h4>
        <br/>
                         <h4>Changes (1)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > <br>|| Name || Description
|| <br></td></tr>
            <tr><td class="diff-unchanged" >| {{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></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">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></td></tr>
            <tr><td class="diff-unchanged" >| {{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. | <br>| {{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 &lt;em&gt;print.a4&lt;/em&gt;.
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. | <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h1><a name="Servlets-ServletsandScripts"></a>Servlets and Scripts</h1>

<p>Servlets can be registered as OSGi services. The following service reference properties
are defined for Servlets defined as OSGi services of type <tt>javax.servlet.Servlet</tt>:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Name </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>sling.servlet.paths</tt> </td>
<td class='confluenceTd'> 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> (<tt>servletresolver.paths</tt>) configuration setting of the
<tt>SlingServletResolver</tt> service.</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>sling.servlet.resourceTypes</tt> </td>
<td class='confluenceTd'> 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 <tt>sling.servlet.paths</tt> property is set. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>sling.servlet.selectors</tt> </td>
<td class='confluenceTd'> 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 &lt;em&gt;print.a4&lt;/em&gt;. The property value must either
be a single String, an array of Strings or a Vector of Strings. This property is ignored if
the <tt>sling.servlet.paths</tt> property is set. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>sling.servlet.extensions</tt> </td>
<td class='confluenceTd'> 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 <tt>sling.servlet.paths</tt> property is set.
</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>sling.servlet.methods</tt> </td>
<td class='confluenceTd'> 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 <tt>sling.servlet.paths</tt> 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>
</tr>
<tr>
<td class='confluenceTd'> <tt>sling.servlet.prefix</tt> </td>
<td class='confluenceTd'> 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. </td>
</tr>
</tbody></table>
</div>


<p>A <tt>SlingServletResolver</tt> listens for <tt>Servlet</tt>services
and - given the correct service registration properties - provides the servlets as resources
in the (virtual) resource tree. Such servlets are provided as <tt>ServletResource</tt>
instances which adapt to the <tt>javax.servlet.Servlet</tt> class.</p>

<p>For a Servlet registered as an OSGi service to be used by the Sling Servlet Resolver,
the either or both of the <tt>sling.servlet.paths</tt> or the <tt>sling.servlet.resourceTypes</tt>
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 <tt>sling.servlet.paths</tt>
property or constructed from the other <tt>sling.servlet.&#42;</tt> properties
- must be absolute. Any relative path is made absolute by prefixing it with a root path. This
prefix may be set with the <tt>sling.servlet.prefix</tt> service registration
property. If this property is not set, the first entry in the <tt>ResourceResolver</tt>
search path for the <tt>ResourceResolver.getResource(String)</tt> method is used
as the prefix. If this entry cannot be derived, a simpe slash - <tt>/</tt> &#45;
is used as the prefix.</p>

<p>If <tt>sling.servlet.methods</tt> 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>

<h3><a name="Servlets-Automatedtests"></a>Automated tests</h3>
<p>The <a href="http://svn.apache.org/repos/asf/sling/trunk/launchpad/test-services/"
class="external-link" rel="nofollow">launchpad/test-services</a> module contains
test servlets that use various combinations of the above properties. </p>

<p>The <a href="http://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests/"
class="external-link" rel="nofollow">launchpad/integration-tests</a> module contains
a number of tests (like the <a href="http://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/servlets/resolution/ExtensionServletTest.java"
class="external-link" rel="nofollow">ExtensionServletTest</a> 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><a name="Servlets-Example%3ARegistrationbyPath"></a>Example: Registration
by Path</h3>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>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" \]
</pre>
</div></div>

<p>A Servlet service registered with these properties is registered under the following
paths:</p>

<ul>
	<li><tt>/libs/sling/sample/html</tt></li>
	<li><tt>/libs/sling/sample/txt</tt></li>
</ul>


<p>The registration properties <tt>sling.servlet.resourceTypes</tt>, <tt>sling.servlet.selectors</tt>
and <tt>sling.servlet.extensions</tt> <b>are ignored</b> because the
<tt>sling.servlet.paths</tt> property is set.</p>


<h3><a name="Servlets-Example%3ARegistrationbyResourceTypeetc."></a>Example:
Registration by Resource Type etc.</h3>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>sling.servlet.resourceTypes = \[ "sling/unused" \]
sling.servlet.selectors = \[ "img", "tab" \]
sling.servlet.extensions = \[ "html", "txt", "json" \]
</pre>
</div></div>

<p>A Servlet service registered with these properties is registered under the following
paths:</p>

<ul>
	<li><tt><em>prefix</em>/sling/unused/img/html</tt></li>
	<li><tt><em>prefix</em>/sling/unused/img/txt</tt></li>
	<li><tt><em>prefix</em>/sling/unused/img/json</tt></li>
	<li><tt><em>prefix</em>/sling/unused/tab/html</tt></li>
	<li><tt><em>prefix</em>/sling/unused/tab/txt</tt></li>
	<li><tt><em>prefix</em>/sling/unused/tab/json</tt></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 <tt><em>prefix</em></tt>
is defined.</p>


<h2><a name="Servlets-ScriptsareServlets"></a>Scripts are Servlets</h2>


<p>The Sling API defines a <tt>SlingScript</tt> interface which is used
to represent (executable) scripts inside of Sling. This interface is implemented in the <tt>scripting/core</tt>
bundle in the <tt>DefaultSlingScript</tt> class which also implements the <tt>javax.servlet.Servlet</tt>.</p>

<p>To further simplify the access to scripts from the Resource tree, the <tt>scripting/core</tt>
bundle registers an <tt>AdapterFactory</tt> to adapt Resources to Scripts and
Servlets (the <tt>SlingScriptAdapterFactory</tt>). In fact the adapter factory
returns instances of the <tt>DefaultSlingScript</tt> class for both Scripts and
Servlets.</p>

<p>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.</p>


<h2><a name="Servlets-"></a></h2>


<h2><a name="Servlets-DefaultServlet%28s%29"></a>Default Servlet(s)</h2>

<p>As explained in the Resolution Process section above, a default Servlet is selected
if no servlet (or script) for the current resource type can be found. To make the provisioning
of a default Servlet as versatile as provisioning per resource type Servlets (or scripts),
the default Servlet is selected with just a special resource type <tt>sling/servlet/default</tt>.</p>

<p>The actual Servlet or Script called as the default Servlet is resolved exactly the
same way as for any resource type. That is, also for the default Servlet selection, the request
selectors and extension or method are considered. Also, the Servlet may be a Servlet registered
as an OSGi service or it may be a Script stored in the repository or provided by any bundle.</p>

<p>Finally, if not even a registered default Servlet may be resolved for the request,
because none has been registered, the <tt>servlets/resolver</tt> bundle provides
a fall back the <tt>DefaultServlet</tt> with the following functionality:</p>

<ul>
	<li>If an <tt>NonExistingResource</tt> was created for the request the
<tt>DefaultServlet</tt> sends a 404 (Not Found)</li>
	<li>Otherwise the <tt>DefaultServlet</tt> sends a 500 (Internal Server
Error), because normally at least a <tt>NonExistingResource</tt> should be created</li>
</ul>


<h2><a name="Servlets-OptingServletinterface"></a>OptingServlet interface</h2>
<p>If a registered servlet implements the OptingServlet interface, Sling uses that servlet's
<tt>accepts(SlingHttpServletRequest request)</tt> method to refine the servlet
resolution process.</p>

<p>In this case, the servlet is only selected for processing the current request if
its <tt>accept</tt> method returns true.</p>


<h2><a name="Servlets-ErrorHandlerServlet%28s%29orScripts"></a>Error Handler
Servlet(s) or Scripts</h2>

<p>Error handling support is now described on the <a href="/confluence/display/SLINGxSITE/Errorhandling"
title="Errorhandling">Errorhandling</a> page.</p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/SLINGxSITE/Servlets">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=2329797&revisedVersion=12&originalVersion=11">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/SLINGxSITE/Servlets?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message