ZK Configuration Reference/zk.xml/The listener Element

To declare a listener, you have to add the listener element to zk.xml. You could specify any number of listener elements. Each of them could have two child elements, description and listener-class, where description is optional.

 <zk>
     <listener>
         <listener-class>my.MyInit</listener-class>
    </listener>
 </zk>

The type of a listener depends on what interface it implements. For example, if a listener implements the EventThreadInit interface, then it is used to listen when an event processing thread is initialized. A listener could implement multiple interfaces and it will be used whenever the corresponding interface is about to call.

The org.zkoss.zk.ui.event.EventThreadInit Interface

EventThreadInit is implemented by a listener class that will be used to initialize an event processing thread, before an event is dispatched to it for processing.

If a listener implements this interface, an instance is created, and then the prepare method is called in the main thread (aka., the servlet thread), before processing an event. Then, the init method is called in the event processing thread.

If a developer wants to prevent an event from being processed, he can throw an exception in the prepare method or the init method.

A typical use of this feature is to implement auto-authentication. For example, JBoss required you to call SecurityAssociation.setPrincipal to grant permissions of a user to the event processing thread, as described in the Initialization Before Processing Each Event section, the Event Listening and Processing chapter.

The org.zkoss.zk.ui.event.EventThreadCleanup interface

EventThreadCleanup is implemented by a listener class that will be used to cleanup an event processing thread, after it has processed an event.

If a listener implements this interface, an instance is created, and then the cleanup method is called in the event processing thread after the thread processes the event. Then, the complete method is called in the main thread (aka., the servlet thread), after the main thread is resumed.

Note: The complete method won't be called if the corresponding cleanup method threw an exception.

A typical use of this feature is to clean up unclosed transaction.

Once registered, an instance is constructed and the cleanup method is called after leaving the event processing thread.

The org.zkoss.zk.ui.event.EventThreadSuspend interface

EventThreadSuspend is implemented by a listener class that will be called before an event processing thread is going to be suspended.

If a listener implements this interface, an instance is created, and then the beforeSuspend method, when an event processing thread is going to suspended. It executes in the event processing thread.

A developer can prevent can prevent an event processing thread from being suspended by throwing an exception.

A typical use of this feature is to limit the number of suspended threads.

The org.zkoss.zk.ui.event.EventThreadResume interface

EventThreadResume is implemented by a listener class that will be called after an event processing thread is resumed or aborted.

If a listener implements this interface, an instance is created, and then the beforeResume method is called in the main thread (aka., the servlet thread), when a suspended event thread is being resumed. Then, the afterResume method is called in the event processing thread after the thread is resumed successfully.

If a developer wants to prevent an event from being resumed, he can throw an exception in the beforeResume method.

Notice that beforeResume executes in the main thread, so it shares the same thread-local storage with the main thread. On the other hand, afterResume executes in the event processing thread, so it shares the same thread-local storage with the event thread (and application event listeners).

In additions to resuming normally, a suspended event processing thread might be aborted abnormally. For example, when the desktop is being destroyed, all suspended event threads will be aborted. When the suspended event processing thread is aborted, an instance is created, and the abortResume method is called in the main thread.

Note: If a suspended event thread is aborted, none of the beforeResume and afterResume is called. Moreover, the cleanup and complete methods of EventThreadCleanup won't be called, either. Thus, you have to handle all necessary cleanups in abortResume.

The org.zkoss.zk.ui.util.EventInterceptor interface

EventInterceptor is implemented by a listener class that will be used to intercept when an event is sent, posted and processed.

Once registered, an instance is created and shared within the whole application. If you want to intercept events only for a particular desktop, use Desktop.addListener(Object).

The org.zkoss.zk.ui.util.WebAppInit interface

WebAppInit is implemented by a listener class that will be used to initialize a ZK application.

When a ZK application is created, it invokes the init method of this interface such that developers could plug the application-specific codes to initialize the application.

The org.zkoss.zk.ui.util.WebAppCleanup interface

WebAppCleanup is implemented by a listener class that will be used to cleanup a ZK application that is being destroyed.

When a ZK application is going to be destroyed, it invokes the cleanup method of this interface such that developers could plug the application-specific codes to cleanup the application.

The org.zkoss.zk.ui.util.SessionInit interface

SessionInit interface is implemented by a listener class that will be used to initialize a new session.

When ZK Loader created a new session, it invokes the init method of this interface such that developers could plug the application-specific codes to initialize a session.

A developer can prevent a session from being created by throwing an exception in the init method.

The org.zkoss.zk.ui.util.SessionCleanup interface

SessionCleanup is implemented by a listener class that will be used to cleanup a session that is being destroyed.

When ZK Loader is going to destroy a session, it invokes the cleanup method of this interface such that developers could plug the application-specific codes to cleanup a session.

The org.zkoss.zk.ui.util.DesktopInit interface

DesktopInit is implemented by a listener class that will be used to initialize a new desktop.

When ZK Loader created a new desktop, it invokes the init method of this interface such that developers could plug the application-specific codes to initialize a desktop.

A developer can prevent a desktop from being created by throwing an exception in the init method.

The org.zkoss.zk.ui.util.DesktopCleanup interface

DesktopCleanup is implemented by a listener class that will be used to cleanup a desktop that is being destroyed.

When ZK Loader is going to destroy a desktop, it invokes the cleanup method of this interface such that developers could plug the application-specific codes to cleanup a desktop.

The org.zkoss.zk.ui.util.ExecutionInit interface

ExecutionInit is implemented by a listener class that will be used to initialize a new execution.

When ZK Loader and Update Engine created a new execution, it invokes the init method of this interface such that developers could plug the application-specific codes to initialize an execution.

Tip: Executions might be stacked. To know whether it is the first execution since a (Servlet) request is processed, you can check whether the parent argument is null.

A developer can prevent an execution from being created by throwing an exception in the init method.

The org.zkoss.zk.ui.util.ExecutionCleanup interface

ExecutionCleanup is implemented by a listener class that will be used to cleanup an execution that is being destroyed.

When ZK Loader is going to destroy an execution, it invokes the cleanup method of this interface such that developers could plug the application-specific codes to cleanup an execution.

The org.zkoss.zk.ui.util.Composer interface

[since 5.0.1]

Composer is implemented by a listener class that can process the creation of ZK pages like a composer specified in the apply attribute. It is also known as system-level composers.

When a ZK page, including ZK pages and richlets, is created, ZK will instantiate one instance for each registered system-level composer and the invoke the doAfterCompose method with each root component. The system-level composer is usually used to post-process ZK pages, such as adding a trademark. If you want to process only certain pages, you can check the request path by calling the getRequestPath method of the desktop.

If the system-level composer also implements the org.zkoss.zk.ui.util.ComposerExt interface, it can be used to handle more situations, such as exceptions, like a regular composer can do.

If the system-level composer also implements the org.zkoss.zk.ui.util.FullComposer interface, all its methods will be invoked when each component is created. It provides the finest grain of control but a wrong implementation might degrade the performance a bit.

Notice that since a new instance of the composer is created for each page, there is no threading issues.

Richlet

A system-level composer can implement ComposerExt to handle exception such as doCatch and doFinally. However, doBeforeCompose and doBeforeComposeChildren won't be called.

FullComposer is not applicable to richlets. In other words, system-level composers are called only for the root components.

The org.zkoss.zk.ui.util.URIInterceptor interface

URIInterceptor is implemented by a listener class that will be used to intercept the retrieving of ZUML pages with the associated URI. Once registered, an instance of the specified class is created and shared within the whole application. Then, the request method is invoked, each time the application wants to retrieve the page definition of a page based on an URI.

A typical use of this interface is to ensure the current user has the authority to access the certain URI.

You can register any number of URI interceptors (URIInterceptor).

Note:

1. Unlike ExecutionInit and many other listeners, an instance of the registered URIInterceptor is created at the time of registration, and then it is shared by the whole application. Thus, you have to make sure it can be accessed concurrently.

The org.zkoss.zk.ui.util.RequestInterceptor interface

RequestInterceptor is implemented by a listener class that will be used to intercept each request made to ZK Loader and ZK Update Engine. Once registered, an instance of the specified class is created and shared within the whole application. Then, the request method is invoked, each time a request is received by ZK Loader or ZK Update Engine.

A typical use of this interface is to determine the locale and/or time zone of the request. Refer to the Developer's Guide for more information.

You can register any number of the request interceptors (RequestInterceptor).

Note:

1. Unlike ExecutionInit and many other listeners, an instance of the registered RequestInterceptor is created at the time of registration, and then it is shared by the whole application. Thus, you have to make sure it can be accessed concurrently.
2. The request parameters will be parsed with the proper locale and character encoding, after the RequestInterceptor.request(Session, Object, Object) method is called. It is not recommended to call the getParameter or getParameterValues methods (of javax.servlet.ServletRequest) in this method.

The org.zkoss.zk.ui.util.UiLifeCycle interface

UiLifeCycle is implemented by a listener class that will be used to handle something dependin on the life cycle of UI, such as attaching a component to a page, moving a component and so on. Once registered, an instance of the specified class is created and shared within the whole application.

The org.zkoss.zk.ui.util.PerformanceMeter interface

PerformanceMeter is implemented by a listener that will measure the performance. Unlike other listeners, there is at most one performance meter listener for each Web application. If you like, you can chain them together manually.

The org.zkoss.zk.ui.util.Monitor interface

Monitor is implemented by a listener that will be used to monitor the statuses of ZK. Unlike other listener, there is at most one monitor listener for each Web application. If you like, you can chain them together manually.

ZK provides an implementation named Statistic, which accumulates the statistic data in the memory. It is a good starting point to understand the load of your ZK application.