01: /* EventThreadCleanup.java
02:
03: {{IS_NOTE
04: Purpose:
05:
06: Description:
07:
08: History:
09: Mon Mar 6 23:18:09 2006, Created by tomyeh
10: }}IS_NOTE
11:
12: Copyright (C) 2006 Potix Corporation. All Rights Reserved.
13:
14: {{IS_RIGHT
15: This program is distributed under GPL Version 2.0 in the hope that
16: it will be useful, but WITHOUT ANY WARRANTY.
17: }}IS_RIGHT
18: */
19: package org.zkoss.zk.ui.event;
20:
21: import java.util.List;
22: import org.zkoss.zk.ui.Component;
23:
24: /**
25: * Used to clean the event processing thread.
26: *
27: * <p>How this interface is used.
28: * <ol>
29: * <li>First, you specify a class that implements this interface
30: * in WEB-INF/zk.xml as a listener.
31: * </li>
32: * <li>Then, an instance of the specified class is constructed and {@link #cleanup}
33: * is invoked when the event processing thread has processed an event,
34: * and then {@link #complete} of the same instance is called in the servlet
35: * thread.</li>
36: * </ol>
37: *
38: * <p>Thus, the typical use is to cleaup un-closed transactions
39: * when {@link #cleanup} is called.
40: *
41: * @author tomyeh
42: */
43: public interface EventThreadCleanup {
44: /** Cleans up the event processing thread.
45: * It is called, after a event processing thread has processed an event.
46: *
47: * <p>If this method threw an exception and errs is empty, the exception will
48: * be propagated back to the servlet thread and then reported to the user.
49: *
50: * <p>Note: {@link #cleanup} is called first in the event processing thread,
51: * and then {@link #complete} is called in the servlet thread.
52: * Note: {@link #complete} of an {@link EventThreadCleanup} instance is called
53: * only if {@link #cleanup} called against the same instnce
54: * didn't throw any exception.
55: *
56: * <p>If the use of the event thread is disabled
57: * ({@link org.zkoss.zk.ui.util.Configuration#isEventThreadEnabled}
58: * returns false), this method is also invoked in the Servlet thread.
59: *
60: * @param errs a list of exceptions (java.lang.Throwable) if any exception
61: * occured before this method is called, or null if no exeption at all.
62: * Note: you can manipulate the list directly to add or clean up exceptions.
63: * For example, if exceptions are fixed correctly, you can call errs.clear()
64: * such that no error message will be displayed at the client.
65: */
66: public void cleanup(Component comp, Event evt, List errs)
67: throws Exception;
68:
69: /** Called in the serlvet thread to clean up.
70: * It is called after {@link #cleanup} is called.
71: *
72: * <p>Note: {@link #cleanup} is called first in the event processing thread,
73: * and then {@link #complete} is called in the servlet thread.
74: */
75: public void complete(Component comp, Event evt) throws Exception;
76: }
|