Author: buildbot
Date: Tue Dec 22 05:19:42 2015
New Revision: 976119
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/cache/main.pageCache
websites/production/tapestry/content/overriding-exception-reporting.html
websites/production/tapestry/content/runtime-exceptions.html
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified:
websites/production/tapestry/content/overriding-exception-reporting.html
==============================================================================
--- websites/production/tapestry/content/overriding-exception-reporting.html
(original)
+++ websites/production/tapestry/content/overriding-exception-reporting.html
Tue Dec 22 05:19:42 2015
@@ -131,7 +131,7 @@
</div>
</li></ul>
-</div><p>Of course, one of the first questions anyone asks is "How do I turn
it off?" This exception reporting is very helpful for developers but its easy
to see it as terrifying for potential users. Catching runtime exceptions can be
a very useful way of handling rarely occurring exceptions even in production,
and there's no reason to throw away Tapestry's default error reporting just to
handle a few specific exceptions. From version 5.4 (for previous versions, the
functionality is available as an external, third-party module
tapestry-exceptionpage), you can contribute exception handles and/or exception
pages for specific exception types. Refer back to <a
href="runtime-exceptions.html">Runtime Exceptions</a> page for more
information. Read on if you want to completely replace Tapestry's default
exception handling.</p><h2
id="OverridingExceptionReporting-Version1:ReplacingtheExceptionReportPage">Version
1: Replacing the Exception Report Page</h2><p>Let's start with a page that fire
s an exception from an event handler method.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>ActionFail.tml</b></div><div
class="codeContent panelContent pdl">
+</div><p>Of course, one of the first questions anyone asks is "How do I turn
it off?" This exception reporting is very helpful for developers but its easy
to see it as terrifying for potential users. Catching runtime exceptions can be
a very useful way of handling rarely occurring exceptions even in production,
and there's no reason to throw away Tapestry's default error reporting just to
handle a few specific exceptions. From version 5.4 (for previous versions, the
same functionality is available as a <a class="external-link"
href="http://www.tynamo.org/tapestry-exceptionpage+guide/";
rel="nofollow">third-party module tapestry-exceptionpage</a>), you can
contribute exception handles and/or exception pages for specific exception
types. Refer back to <a href="runtime-exceptions.html">Runtime Exceptions</a>
page for more information. Read on if you want to completely replace Tapestry's
default exception handling.</p><h2
id="OverridingExceptionReporting-Version1:ReplacingtheExceptionR
eportPage">Version 1: Replacing the Exception Report Page</h2><p>Let's start
with a page that fires an exception from an event handler method.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width:
1px;"><b>ActionFail.tml</b></div><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"> <html
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd"; t:type="layout"
title="Action Fail">
<p>
<t:actionlink t:id="fail" class="btn btn-large
btn-warning">Click for Exception</t:actionlink>
Modified: websites/production/tapestry/content/runtime-exceptions.html
==============================================================================
--- websites/production/tapestry/content/runtime-exceptions.html (original)
+++ websites/production/tapestry/content/runtime-exceptions.html Tue Dec 22
05:19:42 2015
@@ -59,7 +59,7 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p>Feedback is vitally important
when developing an application, and that is one of the areas where Tapestry has
always exceled.</p><p>Especially during development, requests can fail. There
can be errors in templates, broken code in your application, or something
unexpected.</p><p>Tapestry has a built-in exception report page that captures
an amazing wealth of information:</p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image confluence-content-image-border" width="500"
src="runtime-exceptions.data/Exception%20-%20Stack%20Trace%20.png"></span></p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image confluence-content-image-border" width="500"
src="runtime-exceptions.data/Exception%20-%20Request.png"></span></p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="co
nfluence-embedded-image confluence-content-image-border" height="443"
width="500"
src="runtime-exceptions.data/Application_Exception.png"></span></p><p>This
exception report features:</p><ul><li>The full stack of exceptions, top to
bottom.</li><li>All non-null properties of each exception.</li><li>The stack
trace <em>at the deepest
level</em>.</li><li>Key <strong>request</strong> properties, header,
attributes, and
parameters.</li><li>Key <strong>session</strong><em> </em>propertes</li><li>A
break down of the <em>thread</em> in your application</li><li>A listing
of all JVM System properties<br clear="none"><br clear="none"></li></ul><p>In
addition, Tapestry will write a text file for the exception with a similar
level of detail.</p><p>In production you will want to <a
href="overriding-exception-reporting.html">override the exception report
page</a> (but will likely keep the text file output).</p><p>This exception
report is also built-in to Tapestry's Ajax s
upport. When an Ajax request fails, Tapestry's client-side code will create an
<iframe> to present this same information:</p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image confluence-content-image-border" height="359"
width="500"
src="runtime-exceptions.data/Exception%20-%20Ajax.png"></span></p><p> </p></div>
+ <div id="ConfluenceContent"><p>Feedback is vitally important
when developing an application, and that is one of the areas where Tapestry has
always excelled.</p><p>Especially during development, requests can fail. There
can be errors in templates, broken code in your application, or something
unexpected.</p><p>Tapestry has a built-in exception report page that captures
an amazing wealth of information:</p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image confluence-content-image-border" width="500"
src="runtime-exceptions.data/Exception%20-%20Stack%20Trace%20.png"></span></p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image confluence-content-image-border" width="500"
src="runtime-exceptions.data/Exception%20-%20Request.png"></span></p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="c
onfluence-embedded-image confluence-content-image-border" height="443"
width="500"
src="runtime-exceptions.data/Application_Exception.png"></span></p><p>This
exception report features:</p><ul><li>The full stack of exceptions, top to
bottom.</li><li>All non-null properties of each exception.</li><li>The stack
trace <em>at the deepest
level</em>.</li><li>Key <strong>request</strong> properties, header,
attributes, and
parameters.</li><li>Key <strong>session</strong><em> </em>propertes</li><li>A
break down of the <em>thread</em> in your application</li><li>A listing
of all JVM System properties<br clear="none"><br clear="none"></li></ul><p>In
addition, Tapestry will write a text file for the exception with a similar
level of detail.</p><p>This exception report is also built-in to Tapestry's
Ajax support. When an Ajax request fails, Tapestry's client-side code will
create an <iframe> to present this same information:</p><p><span
class="confluence-embedded-
file-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image confluence-content-image-border" height="359"
width="500"
src="runtime-exceptions.data/Exception%20-%20Ajax.png"></span></p><p>In
production, you may want to <a
href="overriding-exception-reporting.html">override the exception report
page</a> (but will likely keep the text file output). However, Tapestry's (from
version 5.4) default exception reporter also allows you to handle specific
exception types in a pre-determined manner, similar to how servlet spec's
standard error-page/exception-type configuration option allows you to map
exception types to URLs. At times, it's simpler to just catch exceptions at the
outermost layer of your application instead of carrying a typed exception
through multiple layers of abstractions just so you could show a sensible error
message to the user, especially if you can't do anything more clever about it
anyway. Exception type mapping in Tapestry is much more powerfu
l than what the servlet spec dictates. If your email service or an external
payment service goes down, you can't do much more than display an error message
to the user, so why would you need to implement separate pages for each
exception? Often, it'd be nicer if you could just reuse the page template for
any fatal exception and simply display a different error message. In addition
to contributing handlers for specific types of exceptions, you may also provide
context for rendering the same error page template with a different
output.</p><p> </p><p>You can contribute an error page, mapping it to an
exception type:</p><p>    public void
contributeExceptionHandler(MappedConfiguration<Class, Class>
configuration) {</p><p>      
 configuration.add(SmtpNotRespondingException.class,
ServiceFailure.class);</p><p>    }</p><p> </p><p>If a
simple exception type to page mapping doesn't do it for you, you can also contri
bute a custom handler for that particular exception type. An
ExceptionHandlerAssistant can contain arbitrarily complex logic for handling a
specific exception type and use other Tapestry services. If
ExceptionHandlerAssistant.handleRequestException(Throwable exception,
List<Object> exceptionContext) returns an Object representing an URL the
main handler will issue a redirect to that URL. It's valid to return either a
String, a Link or a Class; the last case implies a page class. If the
ExceptionHandlerAssistant returns null, it's assumed that the assistant has
independently handled the exception. You can either contribute an instance of
an ExceptionHandlerAssistant or a class that implements
ExceptionHandlerAssistant. Below, we contribute an instance handling
ServiceExceptions:</p><p>    public void
contributeExceptionHandler(OperationQueue operationQueue,
MappedConfiguration<Class, Class> configuration) {</p><p>  
     final
ExceptionHandlerAssistant assistant = new ExceptionHandlerAssistant()
{</p><p>        @Override</p><p>  
     public Object handleRequestException(Throwable
exception, List<Object> exceptionContext) throws IOException
{</p><p>          ServiceException
serviceException = (ServiceException)exception;</p><p>  
       if
(serviceException.isInterruptedOperationRecoverable()) {</p><p>  
         
 operationQueue.add(serviceException.getInterruptedOperation());</p><p>  
           return
OperationScheduled.class;</p><p>  
       }</p><p>  
       else return
ServiceUnavailable.class;</p><p>       
}</p><p>    
0;   };</p><p>      
 configuration.add(ServiceException.class, assistant);</p><p>  
 }</p><p> </p><p>You can also specify context for the exception page.
For generic exceptions, the context is taken from the exception class name
minus the word "Exception" in case that's how the class name ends. For example,
you have a following class:</p><p> </p><p>    public class
SmtpNotRespondingException extends RuntimeException {</p><p>  
     ...</p><p>    }</p><p> </p><p>If
an SmtpNotRespondingException is thrown during an action request, user is
directed to ServiceFailure page with a String context smtpnotresponding (i.e.
to URL **/servicefailure/smtpnotresponding**). Tapestry-exceptionpage works
both for regular action requests and ajax action requests. In the latter case,
the module will use Javascript to redirect to the error page. If the exception
thrown wasn
't an explicitly specified exception type (i.e. a contributed type), handling
is delegated back to the default Tapestry exception handler.</p><p>If your
custom-handled exception implements the interface *ContextAwareException* you
can fully specify the context for the error page. For example, you could
implement a following Exception class:</p><p>    public class
SmtpNotRespondingException extends RuntimeException implements
ContextAwareException {</p><p>        private
Object[] context;  </p><p>      
 public EmailServiceException(Object[] context) {</p><p>  
         super();</p><p>  
         this.context =
context;</p><p>        }</p><p>  
     // Defined in ContextAwareException
interface</p><p>        public Object[]
getContext() {</p><p>          
 return context;</p><p>      
 }</p><p>    }</p><p> </p><p>This exception handling
mechanism can easily be overused. Typically, if you can handle the exception
locally, you should. Likewise, you shouldn't blindly wrap any checked
exceptions inside runtime exceptions just to avoid writing try-catch blocks in
higher layers. The exceptionpage module is best used for handling serious but
rarely occurring exceptions happening in the action request cycle that you
cannot otherwise cope with.</p></div>
</div>
<div class="clearer"></div>
