Error Handling"

From Documentation
 
(21 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{ZKDevelopersReferencePageHeader}}
 
{{ZKDevelopersReferencePageHeader}}
  
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).
+
 
 +
__TOC__
 +
 
 +
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
 +
# when serving an AU request (aka, an Ajax request).
 +
 
 +
To handle them both, you need to configure them in different places.
  
 
=Error Handling When Loading ZUML Documents=
 
=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.
+
If an uncaught 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,
 
By default, the Web server displays an error page showing the error message and stack trace. For example,
Line 11: Line 19:
 
[[Image:Exception.png]]
 
[[Image:Exception.png]]
  
You can customize the error handling by specifying the error page in <tt>WEB-INF/web.xml</tt> as follows<ref>Please refer to Chapter 10.9 of [http://download.oracle.com/otn-pub/jcp/servlet-3.0-fr-eval-oth-JSpec/servlet-3_0-final-spec.pdf Java Servlet Specification] for more details.</ref>.
+
You can customize the error handling by specifying the error page in <code>WEB-INF/web.xml</code> as follows<ref>Please refer to Chapter 10.9 of [http://download.oracle.com/otn-pub/jcp/servlet-3.0-fr-eval-oth-JSpec/servlet-3_0-final-spec.pdf Java Servlet Specification] for more details.</ref>.
  
 
'''Note:''' When exceptions are thrown during the ZK UI Lifecycle they are wrapped into a <javadoc  type="class">org.zkoss.zk.ui.UiException</javadoc>. If you want to handle your own exceptions you can implement the <javadoc type="interface">org.zkoss.lang.Expectable</javadoc> on your exception type. Exceptions implementing this interface will not be wrapped and can be handled using the <exception-type> element directly.
 
'''Note:''' When exceptions are thrown during the ZK UI Lifecycle they are wrapped into a <javadoc  type="class">org.zkoss.zk.ui.UiException</javadoc>. If you want to handle your own exceptions you can implement the <javadoc type="interface">org.zkoss.lang.Expectable</javadoc> on your exception type. Exceptions implementing this interface will not be wrapped and can be handled using the <exception-type> element directly.
  
'''Note:''' If the exception you want to handle is a checked exception, it must extend <tt>ServletException</tt> or <tt>IOException</tt>. So the Web container can handle them directly in <tt>doGet</tt> or <tt>doPost</tt> method.
+
'''Note:''' If the exception you want to handle is a checked exception, it must extend <code>ServletException</code> or <code>IOException</code>. So the Web container can handle them directly in <code>doGet</code> or <code>doPost</code> method.
  
 
<source lang="xml">
 
<source lang="xml">
Line 27: Line 35:
 
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.
 
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.
  
{| border='1px' | width="500px"
+
{| class='wikitable' | width="100%"
 
! Request Attribute !! Type
 
! Request Attribute !! Type
 
|-
 
|-
Line 49: Line 57:
 
|}
 
|}
  
Then, in the error page, you can display your custom information by the use of these attributes. For example,
+
* If you run with Jakarta EE, need to replace '''javax''' with '''jakarta''' in those attribute names e.g. <code>jakarta.servlet.error.status_code</code>
 +
 
 +
Then, on the error page, you can display your custom information using these attributes. For example:
  
 
<source lang="xml">
 
<source lang="xml">
Line 58: Line 68:
  
 
'''Tips:'''
 
'''Tips:'''
* The error page can be any kind of servlets. In addition to ZUML, you can use JSP or whatever servlet you preferred.
+
* The error page can be any kind of servlets. In addition to ZUML, you can use JSP or whatever servlet you prefer.
 
* From java code the request attributes are accessible via <javadoc class="true"  method="getAttribute(java.lang.String)">org.zkoss.zk.ui.Execution</javadoc> or from the [https://www.zkoss.org/wiki/ZUML_Reference/EL_Expressions/Implicit_Objects_(Predefined_Variables)/requestScope requestScope (implicit object)].
 
* From java code the request attributes are accessible via <javadoc class="true"  method="getAttribute(java.lang.String)">org.zkoss.zk.ui.Execution</javadoc> or from the [https://www.zkoss.org/wiki/ZUML_Reference/EL_Expressions/Implicit_Objects_(Predefined_Variables)/requestScope requestScope (implicit object)].
  
Line 88: Line 98:
 
== Error Handling when the Client Engine crashes ==
 
== Error Handling when the Client Engine crashes ==
  
[[File:error_handling_crash_screen.png|300px|right]]
+
[[File:error_handling_crash_screen.png|center]]
  
In rare cases the client engine stops working before even the error handling is initialized (e.g. when ZK's core scripts fail to download - zk.wpd). In those cases, the configured error handler can't be called and ZK falls back to a very basic error handling.
+
In rare cases, the client engine stops working before even the error handling is initialized (e.g. when ZK's core scripts, e.g. zk.wpd, 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 the screenshot to the right. When this occurs the connection to ZK is usually broken so you can't report errors to the server using ZK's Ajax engine. As the error details are usually visible in the browser's console it's useful to instruct users to report the errors manually or automatically extract and send them to an error handling service that is accessible at that time (not part of ZK).
+
If the client engine didn't initialize within a configurable timeout, it will display a generic error message like the screenshot to the right. When this occurs, the connection to ZK is usually broken. So you can't report errors to the server via ZK's Ajax engine. As the error details are usually visible in the browser's console, it's useful to instruct users to report the errors manually or automatically extract and send them to an error handling service that is accessible at that time (not part of ZK).  
 
 
Please check [[ZK_Configuration_Reference/zk.xml/The_client-config_Element/The_init-crash-script_Element|the list of error codes]]. Both the timeout and the way the error is presented to the user can be configured within the <tt><client-config> </tt>.
 
  
 +
Please check [[ZK_Configuration_Reference/zk.xml/The_client-config_Element/The_init-crash-script_Element|the list of error codes]]. You can configure both the timeout and the error message presented to users with the elements below:
 
* [[ZK_Configuration_Reference/zk.xml/The_client-config_Element/The_init-crash-script_Element|<init-crash-script>]]
 
* [[ZK_Configuration_Reference/zk.xml/The_client-config_Element/The_init-crash-script_Element|<init-crash-script>]]
 
* [[ZK_Configuration_Reference/zk.xml/The_client-config_Element/The_init-crash-timeout_Element|<init-crash-timeout>]]
 
* [[ZK_Configuration_Reference/zk.xml/The_client-config_Element/The_init-crash-timeout_Element|<init-crash-timeout>]]
  
=Error Handling When Serving AU Requests=
+
=Handling Errors Thrown in Event Listeners=
  
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.
+
If an uncaught exception is thrown by an event listener or a command method in a ViewModel (aka. when serving an AU request ), it is handled by the ZK Update Engine. By default, it simply shows an error message to indicate the error.
  
 
For example, suppose we have the following code:
 
For example, suppose we have the following code:
Line 113: Line 122:
 
[[Image:Exception-au.png]]
 
[[Image:Exception-au.png]]
  
You can customize the error handling by specifying the error page in <tt>WEB-INF/zk.xml</tt> as described in [[ZK Configuration Reference/zk.xml/The error-page Element|ZK Configuration Reference]]. For example,
+
== Configure Error Handling Page ==
 +
You can customize the error handling by specifying the error page in <code>WEB-INF/zk.xml</code> as described in [[ZK Configuration Reference/zk.xml/The error-page Element|ZK Configuration Reference]]. For example,
  
 
<source lang="xml">
 
<source lang="xml">
Line 123: Line 133:
 
</source>
 
</source>
  
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.
+
Then, when an error occurs in an event listener, the ZK Update Engine will show the page you specified.
 +
 
 +
Like error handling in loading a ZUML page, you can specify multiple <code><error-page></code>. Each of them is associated with a different exception type, specified in <code><exception-type></code>. When an error occurs, ZK will search the error pages one-by-one until the exception type matches.
  
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.
+
=== Order Matters ===
 +
The order to handle a thrown exception according to its type is based on the <code><error-page></code>'s declaration sequence in zk.xml.
  
In addition, ZK passes a set of request attributes to the error page to describe what happens. These attribute are as follows.
+
== Get Error Information==
 +
In addition, ZK passes a set of request(Execution) attributes to the error page to describe what happens. These attributes are as follows:
  
{| border='1px' | width="500px"
+
{| class='wikitable' | width="100%"
! Request Attribute !! Type
+
! Request Attribute Name !! Type !! Content
 
|-
 
|-
 
| javax.servlet.error.exception_type
 
| javax.servlet.error.exception_type
 
| java.lang.Class
 
| java.lang.Class
 +
| the thrown error object's class i.e. return <code>Throwable.getClass</code>
 
|-
 
|-
 
| javax.servlet.error.message
 
| javax.servlet.error.message
 
| java.lang.String
 
| java.lang.String
 +
| the all thrown error messages combined
 
|-
 
|-
 
| javax.servlet.error.exception
 
| javax.servlet.error.exception
 
| java.lang.Throwable
 
| java.lang.Throwable
 +
| the thrown error object
 
|-  
 
|-  
 
| javax.servlet.error.status_code
 
| javax.servlet.error.status_code
 +
| java.lang.Integer
 +
| 500
 +
|-
 +
| javax.servlet.error.error_page
 
| java.lang.String
 
| java.lang.String
 +
| the error handling page URL configured in zk.xml
 
|}
 
|}
 +
 +
* If you run with Jakarta EE, need to replace '''javax''' with '''jakarta''' in those attribute names e.g. <code>jakarta.servlet.error.status_code</code>
 +
 +
Besides, the error page is created on the same desktop that causes the error, so you can retrieve the relevant information from the desktop e.g. the page URL, <code>getPage().getRequestPath()</code>.
  
 
For example, you can specify the following content as the error page.
 
For example, you can specify the following content as the error page.
Line 169: Line 195:
  
 
[[Image:Exception-au2.png]]
 
[[Image:Exception-au2.png]]
 
'''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'''.
 
  
 
= Handling a Custom Exception =
 
= Handling a Custom Exception =
By default, ZK will wrap your custom exception with <tt>UiException</tt> or <tt>OperationException</tt>. If you want to handle you custom exception, <tt>YourException</tt>, specifically on a specific error page upon its type. Your custom exception class needs to extend specific classes to avoid being wrapped:
+
By default, ZK will wrap your custom exception with <code>UiException</code> or <code>OperationException</code>. If you want to handle your custom exception, <code>YourException</code>, specifically on a specific error page upon its type. Your custom exception class needs to extend specific classes to avoid being wrapped:
  
* For unchecked:<ref>http://tracker.zkoss.org/browse/ZK-2638</ref>
+
== For unchecked:==
 
<source lang='java'>
 
<source lang='java'>
 
public class YourException extends java.lang.RuntimeException{...}
 
public class YourException extends java.lang.RuntimeException{...}
 
</source>
 
</source>
  
* For checked:<ref>http://tracker.zkoss.org/browse/ZK-3679</ref>
+
Ref: http://tracker.zkoss.org/browse/ZK-2638
 +
 
 +
== For checked: ==
 
<source lang='java'>
 
<source lang='java'>
 
public class YourException extends javax.servlet.ServletException{...}
 
public class YourException extends javax.servlet.ServletException{...}
Line 191: Line 215:
 
</source>
 
</source>
  
Because <tt>HttpServlet</tt> only [https://docs.oracle.com/javaee/7/api/javax/servlet/http/HttpServlet.html#doGet-javax.servlet.http.HttpServletRequest-javax.servlet.http.HttpServletResponse- throws these 2 exceptions].
+
Ref: http://tracker.zkoss.org/browse/ZK-3679
  
 +
Because <code>HttpServlet</code> only [https://docs.oracle.com/javaee/7/api/javax/servlet/http/HttpServlet.html#doGet-javax.servlet.http.HttpServletRequest-javax.servlet.http.HttpServletResponse- throws these 2 checked exceptions (ServletException, IOException) above].
  
<references/>
 
  
=Version History=
 
{{LastUpdated}}
 
{| border='1px' | width="100%"
 
! Version !! Date !! Content
 
|-
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
|}
 
  
 
{{ZKDevelopersReferencePageFooter}}
 
{{ZKDevelopersReferencePageFooter}}

Latest revision as of 02:21, 5 March 2024


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:

  1. when loading a ZUML document
  2. when serving an AU request (aka, an Ajax request).

To handle them both, you need to configure them in different places.

Error Handling When Loading ZUML Documents

If an uncaught 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,

Exception.png

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.

Note: If the exception you want to handle is a checked exception, it must extend ServletException or IOException. So the Web container can handle them directly in doGet or doPost method.

<!-- 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
  • If you run with Jakarta EE, need to replace javax with jakarta in those attribute names e.g. jakarta.servlet.error.status_code

Then, on the error page, you can display your custom information using these attributes. For example:

<window title="Error ${requestScope['javax.servlet.error.status_code']}">
    Cause: ${requestScope['javax.servlet.error.message']}    
</window>

Tips:

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");
	}
}

  1. Please refer to Chapter 10.9 of Java Servlet Specification for more details.

Error Handling when the Client Engine crashes

Error handling crash screen.png

In rare cases, the client engine stops working before even the error handling is initialized (e.g. when ZK's core scripts, e.g. zk.wpd, 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 the screenshot to the right. When this occurs, the connection to ZK is usually broken. So you can't report errors to the server via ZK's Ajax engine. As the error details are usually visible in the browser's console, it's useful to instruct users to report the errors manually or automatically extract and send them to an error handling service that is accessible at that time (not part of ZK).

Please check the list of error codes. You can configure both the timeout and the error message presented to users with the elements below:

Handling Errors Thrown in Event Listeners

If an uncaught exception is thrown by an event listener or a command method in a ViewModel (aka. when serving an AU request ), it is handled by the ZK Update Engine. By default, it simply shows 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.

Exception-au.png

Configure Error Handling Page

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 show the page you specified.

Like error handling in loading a ZUML page, you can specify multiple <error-page>. Each of them is associated with a different exception type, specified in <exception-type>. When an error occurs, ZK will search the error pages one-by-one until the exception type matches.

Order Matters

The order to handle a thrown exception according to its type is based on the <error-page>'s declaration sequence in zk.xml.

Get Error Information

In addition, ZK passes a set of request(Execution) attributes to the error page to describe what happens. These attributes are as follows:

Request Attribute Name Type Content
javax.servlet.error.exception_type java.lang.Class the thrown error object's class i.e. return Throwable.getClass
javax.servlet.error.message java.lang.String the all thrown error messages combined
javax.servlet.error.exception java.lang.Throwable the thrown error object
javax.servlet.error.status_code java.lang.Integer 500
javax.servlet.error.error_page java.lang.String the error handling page URL configured in zk.xml
  • If you run with Jakarta EE, need to replace javax with jakarta in those attribute names e.g. jakarta.servlet.error.status_code

Besides, the error page is created on the same desktop that causes the error, so you can retrieve the relevant information from the desktop e.g. the page URL, getPage().getRequestPath().

For example, you can specify the following content as the error page.

<window title="Error ${requestScope['javax.servlet.error.status_code']}"
width="50%" border="normal" mode="modal" closable="true">
	<vlayout>
KillerApp encounters an error: ${requestScope['javax.servlet.error.message']}
		<hlayout style="margin-left:auto; margin-right:auto">
			<button label="Continue" onClick="spaceOwner.detach()"/>
			<button label="Reload" onClick="Executions.sendRedirect(null)"/>
		</hlayout>
	</vlayout>

	<!-- 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.

Exception-au2.png

Handling a Custom Exception

By default, ZK will wrap your custom exception with UiException or OperationException. If you want to handle your custom exception, YourException, specifically on a specific error page upon its type. Your custom exception class needs to extend specific classes to avoid being wrapped:

For unchecked:

public class YourException extends java.lang.RuntimeException{...}

Ref: http://tracker.zkoss.org/browse/ZK-2638

For checked:

public class YourException extends javax.servlet.ServletException{...}

or

public class YourException extends java.io.IOException{...}

Ref: http://tracker.zkoss.org/browse/ZK-3679

Because HttpServlet only throws these 2 checked exceptions (ServletException, IOException) above.




Last Update : 2024/03/05

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.