svn commit: r1444445 - /sling/site/trunk/content/documentation/the-sling-engine/errorhandling.mdtext

[fm...@apache.org]

Author: fmeschbe
Date: Sat Feb  9 21:48:40 2013
New Revision: 1444445

URL: http://svn.apache.org/r1444445
Log:
+= section on resetting the response

Modified:
    sling/site/trunk/content/documentation/the-sling-engine/errorhandling.mdtext

Modified: sling/site/trunk/content/documentation/the-sling-engine/errorhandling.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/the-sling-engine/errorhandling.mdtext?rev=1444445&r1=1444444&r2=1444445&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/the-sling-engine/errorhandling.mdtext (original)
+++ sling/site/trunk/content/documentation/the-sling-engine/errorhandling.mdtext Sat Feb  9 21:48:40 2013
@@ -1,12 +1,27 @@
 Title: Errorhandling
 
-
 The Sling Engine includes support for handling uncaught `Throwable` as well as rendering custom HTTP status code pages. This is implemented by expecting a (single) `org.apache.sling.engine.servlets.ErrorHandler` service to which handling of uncaught `Throwable` and HTTP status responses are delegated.
 
 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.
 
 This page provides more information on how error handler scripts are selected and what is provided out of the box.
 
+[TOC]
+
+## Resetting the Response
+
+Errorhandler scripts and servlets are script with the current response. Before setting
+the status and writing to the response such handlers should do the following:
+
+* Check whether the response has already been committed
+* If the response has been committed:
+    * Reset the response
+    * Set the status code (use `HttpServletResponse.setStatus`)
+    * Set the response content type and character encoding (provided text data is sent back)
+* If the response has already been committed:
+    * Do not try to reset since this would cause an `IllegalStateException`. Also the writer may not be available.
+    * The best that might be done in this case is just log a message at warning or error level along with information about the failure.
+
 
 ## HTTP Status Codes