Error Handling"
Robertwenzel (talk | contribs) m |
Robertwenzel (talk | contribs) |
||
Line 85: | Line 85: | ||
== Error Handling when the Client Engine crashes == | == Error Handling when the Client Engine crashes == | ||
+ | |||
+ | In rare cases the the client engine stops working before even the error handling is initialized (e.g. when the ZK's core scripts fail to download). In those cases the configured error handler can't be called and ZK falls back to a very basic error handling. If the client engine didn't initialize within a configurable timeout it will display a generic error message like this. | ||
+ | |||
+ | [[File:error_handling_crash_screen.png]] | ||
=Error Handling When Serving AU Requests= | =Error Handling When Serving AU Requests= |
Revision as of 08:13, 21 March 2017
Here we describe how to handle errors. An error is caused by an exception that is not caught by the application. An exception might be thrown in two situations: when loading a ZUML document or when serving an AU request (aka, an Ajax request).
Error Handling When Loading ZUML Documents
If an un-caught exception is thrown when loading a ZUML document, it is handled directly by the Web server. In other words, the handling is no different from other servlets.
By default, the Web server displays an error page showing the error message and stack trace. For example,
You can customize the error handling by specifying the error page in WEB-INF/web.xml as follows[1].
Note: When exceptions are thrown during the ZK UI Lifecycle they are wrapped into a UiException. If you want to handle your own exceptions you can implement the Expectable on your exception type. Exceptions implementing this interface will not be wrapped and can be handled using the <exception-type> element directly.
<!-- WEB-INF/web.xml -->
<error-page>
<exception-type>java.lang.Throwable</exception-type>
<location>/WEB-INF/sys/error.zul</location>
</error-page>
Then, when an error occurs on loading a page, the Web server forwards the error page you specified, /error/error.zul. Upon forwarding, the Web server passes a set of request attributes to the error page to describe what happens. These attributes are as follows.
Request Attribute | Type |
---|---|
javax.servlet.error.status_code | java.lang.Integer |
javax.servlet.error.exception_type | java.lang.Class |
javax.servlet.error.message | java.lang.String |
javax.servlet.error.exception | java.lang.Throwable |
javax.servlet.error.request_uri | java.lang.String |
javax.servlet.error.servlet_name | java.lang.String |
Then, in the error page, you can display your custom information by the use of these attributes. For example,
<window title="Error ${requestScope['javax.servlet.error.status_code']}">
Cause: ${requestScope['javax.servlet.error.message']}
</window>
Tips:
- The error page can be any kind of servlets. In addition to ZUML, you can use JSP or whatever servlet you preferred.
- From java code the request attributes are accessible via Execution.getAttribute(String) or from the requestScope (implicit object).
public class ErrorHandlingComposer extends SelectorComposer<Component> {
@WireVariable
private Map<String, Object> requestScope;
@Override
public void doAfterCompose(Component comp) throws Exception {
//via execution.getAttribute()
Execution execution = Executions.getCurrent();
Exception ex1 = (Exception) execution.getAttribute("javax.servlet.error.exception");
//via requestScope map
Exception ex2 = (Exception) requestScope.get("javax.servlet.error.exception");
}
}
- ↑ Please refer to Chapter 10.9 of Java Servlet Specification for more details.
Error Handling when the Client Engine crashes
In rare cases the the client engine stops working before even the error handling is initialized (e.g. when the ZK's core scripts fail to download). In those cases the configured error handler can't be called and ZK falls back to a very basic error handling. If the client engine didn't initialize within a configurable timeout it will display a generic error message like this.
Error Handling When Serving AU Requests
If an uncaught exception is thrown when serving an AU request (aka., an Ajax request; such as caused by an event listener), it is handled by the ZK Update Engine. By default, it simply shows up an error message to indicate the error.
For example, suppose we have the following code:
<button label="Cause Error" onClick='throw new NullPointerException("Unknown Value")'/>
Then, if you click the button, the following error message will be shown.
You can customize the error handling by specifying the error page in WEB-INF/zk.xml as described in ZK Configuration Reference. For example,
<!-- zk.xml -->
<error-page>
<exception-type>java.lang.Throwable</exception-type>
<location>/WEB-INF/sys/error.zul</location>
</error-page>
Then, when an error occurs in an event listener, the ZK Update Engine will create a dialog by the use of the error page you specified, /error/error.zul.
Like error handling in loading a ZUML page, you can specify multiple <error-page> elements. Each of them is associated with a different exception type (the value of <exception-type> element). When an error occurs, ZK will search the error pages one-by-one until the exception type matches.
In addition, ZK passes a set of request attributes to the error page to describe what happens. These attribute are as follows.
Request Attribute | Type |
---|---|
javax.servlet.error.exception_type | java.lang.Class |
javax.servlet.error.message | java.lang.String |
javax.servlet.error.exception | java.lang.Throwable |
For example, you can specify the following content as the error page.
<window title="Error ${requestScope['javax.servlet.error.status_code']}"
width="400px" border="normal" mode="modal" closable="true">
<vbox>
KillerApp encounters an error: ${requestScope['javax.servlet.error.message']}
<hbox style="margin-left:auto; margin-right:auto">
<button label="Continue" onClick="spaceOwner.detach()"/>
<button label="Reload" onClick="Executions.sendRedirect(null)"/>
</hbox>
</vbox>
<!-- optional: record the error for improving the app -->
<zscript>
org.zkoss.util.logging.Log.lookup("Fatal").error(
requestScope.get("javax.servlet.error.exception"));
</zscript>
</window>
Then, when the button is clicked, the following will be shown.
Tips:
- The error page is created at the same desktop that causes the error, so you can retrieve the relevant information from the desktop.
- The order to handle the thrown exception according to it's type is based on the <error-page>'s declaration sequence in zk.xml.
Version History
Version | Date | Content |
---|---|---|