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 > Filters
Date Thu, 11 Mar 2010 10:12:00 GMT
<html>
<head>
    <base href="http://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1519/1/1/_/styles/combined.css?spaceKey=SLINGxSITE&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background-color: white" bgcolor="white">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
     <h2><a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/Filters">Filters</a></h2>
     <h4>Page <b>edited</b> by             <a href="http://cwiki.apache.org/confluence/display/~bdelacretaz">Bertrand
Delacretaz</a>
    </h4>
     Add troubleshooting info
          <div id="versionComment" class="noteMacro" style="display:none; padding: 5px;">
     Add troubleshooting info<br />
     </div>
          <br/>
     <div class="notificationGreySide">
         <h1><a name="Filters-ServletFilterSupport"></a>Servlet Filter Support</h1>

<p>Sling supports filter processing by applying filter chains to the requests before
actually dispatching to the servlet or script for processing. Filters to be used in such filter
processing are plain OSGi services for the type <tt>javax.servlet.Filter</tt>
which of course means that the services implement this interface.</p>

<p>For Sling to pick up a <tt>javax.servlet.Filter</tt> service for filter
processing two service registration properties are inspected:</p>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Property </th>
<th class='confluenceTh'> Type </th>
<th class='confluenceTh'> Default Value </th>
<th class='confluenceTh'> Valid Values </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>filter.scope</tt> </td>
<td class='confluenceTd'> <tt>String</tt> </td>
<td class='confluenceTd'> <tt>request</tt> </td>
<td class='confluenceTd'> <tt>component</tt>, <tt>request</tt>
</td>
<td class='confluenceTd'> Indication of which chain the filter should be added to. By
default a filter is added to the request filter chain. The default value also applies if the
value of this property is any other value than one of the valid values. <b>Using this
default behavior is highly discouraged and will result a logged warning.</b> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>filter.order</tt> </td>
<td class='confluenceTd'> <tt>Integer</tt> </td>
<td class='confluenceTd'> <tt>Integer.MAX_VALUE</tt> </td>
<td class='confluenceTd'> Any <tt>Integer</tt> value </td>
<td class='confluenceTd'> Indication of where to place the filter in the filter chain.
The smaller the number the earlier in the filter chain. This value may span the whole range
of integer values. The default value causes the filter to just be appended to the filter chain.
</td>
</tr>
</tbody></table>

<h2><a name="Filters-FelixWhiteboardCompatibility"></a>Felix Whiteboard
Compatibility</h2>

<p>In order to achive compatibility with Apache Felix's HttpService Whiteboard implementation
(<a href="http://felix.apache.org/site/apache-felix-http-service.html#ApacheFelixHTTPService-UsingtheWhiteboard"
rel="nofollow">http://felix.apache.org/site/apache-felix-http-service.html#ApacheFelixHTTPService-UsingtheWhiteboard</a>),
Sling will skip any filters registered with the <tt>pattern</tt> service registration
property.</p>

<h2><a name="Filters-FilterChains"></a>Filter Chains</h2>

<p>Sling maintains two filter chains: the request filter chain and the component filter
chain.</p>

<p>The filters on the request filter chain are only called once for the complete request
processing. The request level filter chain is comparable to the set of filters configured
as <tt>&lt;dispatcher&gt;REQUEST&lt;/dispatcher&gt;</tt> in Servlet
API 2.5 web applications (see section SRV.6.2.5 Filters and the RequestDispatcher).</p>

<p>The filters on the component filter chain are processed for each included resource
initiated through the RequestDispatcher. The component level filter chain is comparable to
the set of filters configured as <tt>&lt;dispatcher&gt;INCLUDE,FORWARD,ERROR&lt;/dispatcher&gt;</tt>
in Servlet API 2.5 web applications (see section SRV.6.2.5 Filters and the RequestDispatcher).
Note, that it is currently not possible to call filters only on include, forward, or error
or any combination.</p>



<h2><a name="Filters-FilterProcessing"></a>Filter Processing</h2>

<p>Filter processing is part of the Sling request processing, which may be sketched
as follows:</p>

<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'> <em>Request Level</em> </td>
</tr>
<tr>
<td class='confluenceTd'> Authentication </td>
</tr>
<tr>
<td class='confluenceTd'> Resource Resolution </td>
</tr>
<tr>
<td class='confluenceTd'> Servlet/Script Resolution </td>
</tr>
<tr>
<td class='confluenceTd'> Request Level Filter Processing </td>
</tr>
<tr>
<td class='confluenceTd'> <em>Component Level</em> </td>
</tr>
</tbody></table>

<p>The first step of request processing is the <em>Request Level</em> processing
which is concerned with resolving the resource, finding the appropriate servlet and calling
into the request level filter chain. The next step is the <em>Component Level</em>
processing, calling into the component level filters before finally calling the servlet or
script:</p>

<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'> <em>Component Level</em> </td>
</tr>
<tr>
<td class='confluenceTd'> Component Level Filter Processing </td>
</tr>
<tr>
<td class='confluenceTd'> Call Servlet or Script </td>
</tr>
</tbody></table>

<p>When a servlet or script is including another resource for processing through the
<tt>RequestDispatcher</tt> (or any JSP tag or other language feature ultimately
using a <tt>RequestDispatcher</tt>) the following <em>Dispatch</em>
processing takes place:</p>

<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'> <em>Dispatch</em> </td>
</tr>
<tr>
<td class='confluenceTd'> Resolve the resource to dispatch to if not already defined
when getting the <tt>RequestDispatcher</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> Servlet/Script resolution </td>
</tr>
<tr>
<td class='confluenceTd'> <em>Component Level</em> </td>
</tr>
</tbody></table>

<p>Note, that after ensuring the resource to be included (or forwarded to) and resolving
the servlet or script to handle the included (or forwarded) resource, the <em>Component
Level</em> processing takes place as for the general request processing.</p>


<p>As a consequence, request level filters will be called at most once during request
processing (they may not be called at all if a filter earlier in the filter chain decides
to terminate the request) while the component level filters may be called multiple times while
processing a request.</p>

<h2><a name="Filters-Troubleshooting"></a>Troubleshooting</h2>
<p>Apart form the logs which tell you when filters are executed, two Sling plugins provide
information about filters in the OSGi console.</p>

<h3><a name="Filters-RecentRequestsplugin"></a>Recent Requests plugin</h3>
<p>The request traces provided at <tt>/system/console/requests</tt> contain
information about filter execution, as in this example:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>Recent Requests plugin info</b></div><div
class="codeContent panelContent">
<pre class="code-java">
TIMER_START{Request Processing}
...
LOG Resource Path Info: SlingRequestPathInfo: path='/libs/foo/welcome'...
...
LOG Applying request filters
LOG Calling filter: org.apache.sling.portal.container.internal.request.PortalFilter
LOG Calling filter: org.apache.sling.rewriter.impl.RewriterFilter
LOG Calling filter: org.apache.sling.i18n.impl.I18NFilter
LOG Calling filter: org.apache.sling.engine.impl.debug.RequestProgressTrackerLogFilter
LOG Applying <span class="code-keyword">inner</span> filters
LOG Calling filter: com.foo.SomeComponentFilter
LOG Calling filter: com.foo.AnotherComponentFilter
...
TIMER_END{4833,Request Processing} Request Processing
</pre>
</div></div>

<h3><a name="Filters-ConfigStatusplugin"></a>Config Status plugin</h3>
<p>The configuration status page at <tt>/system/console/config</tt> includes
the current list of active filters in its <em>Servlet Filters</em> category, as
in this example:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>Config Status plugin info</b></div><div
class="codeContent panelContent">
<pre class="code-java">
Current Apache Sling Servlet Filter Configuration

Request Filters:
-3000 : class org.apache.sling.portal.container.internal.request.PortalFilter (222)
-2500 : class org.apache.sling.rewriter.impl.RewriterFilter (248)
-700 : class org.apache.sling.i18n.impl.I18NFilter (240)
2147483647 : class org.apache.sling.engine.impl.debug.RequestProgressTrackerLogFilter (231)

Component Filters:
-200 : class com.foo.SomeComponentFilter (564)
1000 : class com.foo.AnotherComponentFilter (348)
</pre>
</div></div>

<p>The first numbers on those lines are the filter priorities, and the last number in
parentheses is the OSGi service ID.</p>
     </div>
     <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href="http://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
       </div>

       <a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/Filters">View
Online</a>
       |
       <a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=115575&revisedVersion=4&originalVersion=3">View
Change</a>
              |
       <a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/Filters?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message