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 > Errorhandling
Date Thu, 11 Mar 2010 08:08: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/Errorhandling">Errorhandling</a></h2>
     <h4>Page <b>edited</b> by             <a href="http://cwiki.apache.org/confluence/display/~fmeschbe">Felix
Meschberger</a>
    </h4>
     
          <br/>
     <div class="notificationGreySide">
         <h1><a name="Errorhandling-HandlingErrors"></a>Handling Errors</h1>

<p>The Sling Engine includes support for handling uncaught <tt>Throwable</tt>
as well as rendering custom HTTP status code pages. This is implemented by expecting a (single)
<tt>org.apache.sling.engine.servlets.ErrorHandler</tt> service to which handling
of uncaught <tt>Throwable</tt> and HTTP status responses are delegated.</p>

<p>The Sling Servlet Resolver bundle implements this interface by providing an elaborate
mechanism to find the correct error handling script or servlet using the same algorithms as
are used to select the scripts or servlets to handle regular requests.</p>

<p>This page provides more information on how error handler scripts are selected and
what is provided out of the box.</p>


<h2><a name="Errorhandling-HTTPStatusCodes"></a>HTTP Status Codes</h2>

<p>The Sling engine implements the <tt>HttpServletResponse.sendError</tt>
methods by calling the <tt>ErrorHandler.handleError(int status, String message, SlingHttpServletRequest
request, SlingHttpServletResponse response)</tt> method.</p>

<p>The Servlet Resolver bundle implementation looks up a script to handle the status
code as follows:</p>

<ul>
	<li>The status code is converted to a string and used as the request extension. Any
request extensions, selectors or suffixes from the actual request are ignored.</li>
	<li>The same resource type hierarchy is followed to find the script as for regular
script resolution. The difference is that for error handler scripts <tt>sling/servlet/errorhandler</tt>
is used as the implied base resource type (as opposed to <tt>sling/servlet/default</tt>
for regular script resolution.</li>
</ul>


<p><b>Examples:</b></p>

<ul>
	<li>An application provider my provide a default handler for the 404/NOT FOUND status.
This script might be located in <tt>/libs/sling/servlet/errorhandler/404.jsp</tt>.</li>
	<li>An programmer might provide a handler for the 403/FORBIDDEN status in <tt>/apps/sling/servlet/errorhandler/403.esp</tt>.</li>
</ul>



<h2><a name="Errorhandling-UncaughtThrowables"></a>Uncaught Throwables</h2>

<p>To handle uncaught Throwables the simple name (<tt>Class.getSimpleName()</tt>)
of the <tt>Throwable</tt> class is used as request extension. Similarly to the
Java try-catch clauses the class hierarchy is supported. That is to handle an uncaught <tt>FileNotFoundException</tt>,
the names <tt>FileNotFoundException</tt>, <tt>IOException</tt>, <tt>Exception</tt>,
<tt>Throwable</tt> are checked for a Servlet and the first one found is then used.
Again, the Serlvet may be a Servlet registered as an OSGi service or may be a plain script
stored in the JCR repository or provided through some custom Resource provider.</p>

<p><b>Example:</b><br/>
To register a catch-all handler for any uncaught Throwables you might create a script <tt>/apps/sling/servlet/errorhandler/Throwable.esp</tt>.</p>

<p><b>Note:</b> If no script or servlet to handle an uncaught <tt>Throwable</tt>
is registered, the default handler kicks in, which sends back a 500/INTERNAL SERVER ERROR
response containing the <tt>Throwable</tt> and the stack trace. This response
is <b>not</b> handled by the HTTP Status Code handling described above because
the response status is sent using <tt>HttpServletResponse.setStatus(int, String)</tt>.
To prevent this default response you have to implement a catch-all handler for the <tt>Throwable</tt>
class as shown in the example.</p>

<h2><a name="Errorhandling-DefaultHandler"></a>Default Handler</h2>

<p>The Sling Servlet Resolver bundle provides a default error handler servlet which
is used if the algorithms described above do not resolve to a handler script or servlet. The
provided error handler servlet does the following:</p>

<ul>
	<li>Print a descriptive message, which is the <tt>javax.servlet.error.message</tt>
request attribute by default</li>
	<li>Print a stacktrace if the <tt>javax.servlet.error.exception</tt> is
set</li>
	<li>Dump the request progress tracker</li>
</ul>


<p>Starting with Sling Servlet Resolver version 2.0.10 the default error handler servlet
is looked up using the string <tt>default</tt> as the request extension and the
provided default servlet is registered as <tt>&lt;prefix&gt;/sling/servlet/errorhandler/default.servlet</tt>
where &lt;prefix&gt; is the last entry in the resource resolver search path, <tt>/libs</tt>
by default.</p>

<p>Thus to overwrite the default error handler servlet provide a servlet or script for
the <tt>default</tt> extension, for example <tt>/apps/sling/servlet/errorhandler/default.groovy</tt>.</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/Errorhandling">View
Online</a>
       |
       <a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=5144889&revisedVersion=4&originalVersion=3">View
Change</a>
              |
       <a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/Errorhandling?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message