Author: buildbot
Date: Thu Dec 24 05:19:40 2015
New Revision: 976267
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/cache/main.pageCache
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/runtime-exceptions.html
==============================================================================
--- websites/production/tapestry/content/runtime-exceptions.html (original)
+++ websites/production/tapestry/content/runtime-exceptions.html Thu Dec 24
05:19:40 2015
@@ -27,6 +27,14 @@
</title>
<link type="text/css" rel="stylesheet" href="/resources/space.css" />
+ <link href='/resources/highlighter/styles/shCoreCXF.css'
rel='stylesheet' type='text/css' />
+ <link href='/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet'
type='text/css' />
+ <script src='/resources/highlighter/scripts/shCore.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushJava.js'
type='text/javascript'></script>
+ <script>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -59,7 +67,43 @@
</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 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_Stack_Trace.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_Request.png"></span></p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="confluence-embedde
d-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 conf
luence-embedded-manual-size"><img class="confluence-embedded-image
confluence-content-image-border" height="359" width="500"
src="runtime-exceptions.data/Exception_Ajax.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
powerful 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
contribute a custom handler f
or 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 ExceptionHandlerAssista
nt 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>        };</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 specif
ied 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>&
#160;           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 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_Stack_Trace.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_Request.png"></span></p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="confluence-embedde
d-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 conf
luence-embedded-manual-size"><img class="confluence-embedded-image
confluence-content-image-border" height="359" width="500"
src="runtime-exceptions.data/Exception_Ajax.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
powerful 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>You can contribute
an error page, mapping it to an exception type:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> public void
contributeExceptionHandler(MappedConfiguration<Class, Class>
configuration) {
+ configuration.add(SmtpNotRespondingException.class,
ServiceFailure.class);
+ }</pre>
+</div></div><p>If a simple exception type to page mapping doesn't do it for
you, you can also contribute a custom handler for that particular exception
type. An <em>ExceptionHandlerAssistant</em> can contain arbitrarily complex
logic for handling a specific exception type and use other Tapestry services.
If <em>ExceptionHandlerAssistant.handleRequestException(Throwable exception,
List<Object> exceptionContext)</em> 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
<em>ExceptionHandlerAssistant</em> returns null, it's assumed that the
assistant has independently handled the exception. You can either contribute an
instance of an <em>ExceptionHandlerAssistant</em> or a class that implements
<em>ExceptionHandlerAssistant</em>. Below, we contribute an instance handling
<em>ServiceException</em>s:</p><div class="code panel pdl" style="border-wid
th: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> public void
contributeExceptionHandler(OperationQueue
+operationQueue, MappedConfiguration<Class, Class> configuration) {
+ final ExceptionHandlerAssistant assistant = new
ExceptionHandlerAssistant() {
+ @Override
+ public Object handleRequestException(Throwable exception,
List<Object> exceptionContext) throws IOException {
+ ServiceException serviceException = (ServiceException)exception;
+ if (serviceException.isInterruptedOperationRecoverable()) {
+ operationQueue.add(serviceException.getInterruptedOperation());
+ return OperationScheduled.class;
+ }
+ else return ServiceUnavailable.class;
+ }
+ };
+ configuration.add(ServiceException.class, assistant);
+ }</pre>
+</div></div><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><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class SmtpNotRespondingException extends
RuntimeException {
+ ...
+}</pre>
+</div></div><p>If an <em>SmtpNotRespondingException</em> is thrown during an
action request, user is directed to <em>ServiceFailure</em> page with a String
context smtpnotresponding (i.e. to URL
<strong>/servicefailure/smtpnotresponding</strong>). The contributed exception
handling 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 is not one of the contributed types, the exception is
handled like any other exception, as explained above.</p><p>If your
custom-handled exception implements the interface
<em>org.apache.tapestry5.ContextAwareException</em> you can fully specify the
context for the error page. For example, you could implement a following
Exception class:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> public class SmtpNotRespondingException extends
RuntimeException implements ContextAwareException {
+ private Object[] context;
+ public EmailServiceException(Object[] context) {
+ super();
+ this.context = context;
+ }
+ // Defined in ContextAwareException interface
+ public Object[] getContext() {
+ return context;
+ }
+ }</pre>
+</div></div><p>The contributed 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
mechanism for contributed exception types 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>
