Package org.zkoss.zk.ui.event

Interface EventThreadInit

All Known Implementing Classes:

SpringTransactionSynchronizationListener, ThreadLocalListener

public interface EventThreadInit

Used to initialize the event processing thread.

How this interface is used.

1. First, you specify a class that implements this interface in WEB-INF/zk.xml as a listener.
2. Then, even time the engine (in the main thread) is about to process an event, it creates a new instance of the specified class, invokes prepare(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event), and then pass it to the thread processing thread.
3. After the thread processing thread is resumed, it invokes init(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event) to do the initialization.

In other words, prepare(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event) is called in the servlet thread, while init(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event) is called in the event processing thread. Therefore, the typical use is retrieving thread-relevant info in prepare(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event), and then apply them in the event processing thread when init(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event) is called.

Author:

tomyeh

Method Summary

Modifier and Type	Method	Description
boolean	init(Component comp, Event event)	Initialize the event processing thread before processing the event.
void	prepare(Component comp, Event event)	Prepares the initialization at the servlet thread.

Method Detail

prepare

void prepare(Component comp,
             Event event)
      throws java.lang.Exception

Prepares the initialization at the servlet thread.

It is invoked in the servlet thread (and before init(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event)). Thus, you can NOT manipulate the desktop in this method.

If this method throws an exception, it will abort the execution and shows an error message to the end user. Note: EventThreadCleanup.cleanup(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event, java.util.List<java.lang.Throwable>) won't be called if an exception is thrown in this method, since it executes in the main thread.

In addition to throwing an exception, you can prevent an event from processing by returning false in init(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event). The event is ignored 'silently' then.

Throws:

java.lang.Exception

init

boolean init(Component comp,
             Event event)
      throws java.lang.Exception

Initialize the event processing thread before processing the event.

The simplest form is void init(Component c, Event e) {return true;}

Unlike prepare(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event), it is invoked in the event processing thread (and after prepare(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event)). Thus, you can manipulate the desktop in this method such as creating a component.

If you want to prevent an event from processing, you can return false in this method. For example, you might create a highlighted window and return false to prevent the user from accessing, if the system is too busy.

If the use of the event thread is disabled (Configuration.isEventThreadEnabled() returns false), this method is also invoked in the Servlet thread.

If this method throws an exception, it will abort the execution and shows an error message to the end user (unless it is cleaned up by EventThreadCleanup.cleanup(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event, java.util.List<java.lang.Throwable>)).

Returns:

if it is initialized successfully. If false is returned, the event is ignored, i.e., no event handler/listener will be invoked.

Throws:

java.lang.Exception