The listener Element"

From Documentation
m
(25 intermediate revisions by 4 users not shown)
Line 1: Line 1:
__TOC__
+
{{ZKConfigurationReferencePageHeader}}
To declare a listener, you have to add the <tt>listener</tt> element to <tt>zk.xml</tt>. You could specify any number of <tt>listener</tt> elements. Each of them could have two child elements, <tt>description</tt> and <tt>listener-class</tt>, where description is optional.
 
  
<source lang="xml" >
+
'''Syntax:'''
  <zk>
+
  <listener>
     <listener>
+
     <listener-class>''a_class_name''</listener-class>
        <listener-class>my.MyInit</listener-class>
+
</listener>
    </listener>
 
</zk>
 
</source>
 
  
The type of a listener depends on what interface it implements. For example, if a listener implements the <javadoc type="interface">org.zkoss.zk.ui.event.EventThreadInit</javadoc> 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.
+
Specifies the name of the class that implements one of the following interfaces. Depending on the interface(s) it implements, it will be invoked when the corresponding situation occurs.
  
== The org.zkoss.zk.ui.event.EventThreadInit Interface ==
+
{{ZKConfigurationReferenceHeadingToc}}
It 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 <tt>prepare</tt> method is called in the main thread (aka., the servlet thread), before processing an event. Then, the <tt>init</tt> method is called in the event processing thread.
+
{{ZKConfigurationReferencePageFooter}}
 
 
If a developer wants to prevent an event from being processed, he can throw an exception in the <tt>prepare</tt> method or the <tt>init</tt> method.
 
 
 
A typical use of this feature is to implement auto-authentication. For example, JBoss<ref>http://www.jboss.org</ref> required you to call <tt>SecurityAssociation.setPrincipal</tt> 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.
 
 
 
 
 
'''Notes'''
 
<references/>
 
 
 
== The org.zkoss.zk.ui.event.EventThreadCleanup interface ==
 
It 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 <tt>cleanup</tt> method is called in the event processing thread after the thread processes the event. Then, the <tt>complete</tt> method is called in the main thread (aka., the servlet thread), after the main thread is resumed.
 
 
 
'''Note''': The <tt>complete</tt> method won't be called if the corresponding <tt>cleanup</tt> method threw an exception.
 
 
 
A typical use of this feature is to clean up unclosed transaction.
 
 
 
Once registered, an instance is constructed and the <tt>cleanup</tt> method is called after leaving the event processing thread.
 
 
 
== The org.zkoss.zk.ui.event.EventThreadSuspend interface ==
 
It 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 <tt>beforeSuspend</tt> 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 ==
 
It 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 <tt>beforeResume</tt> method is called in the main thread (aka., the servlet thread), when a suspended event thread is being resumed. Then, the <tt>afterResume</tt> 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 <tt>beforeResume</tt> method.
 
 
 
Notice that <tt>beforeResume</tt> executes in the main thread, so it shares the same thread-local storage with the main thread. On the other hand, <tt>afterResume</tt> 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 <tt>abortResume</tt> method is called in the main thread.
 
 
 
'''Note''': If a suspended event thread is aborted, none of the <tt>beforeResume</tt> and <tt>afterResume</tt> is called. Moreover, the <tt>cleanup</tt> and <tt>complete</tt> methods of <tt>EventThreadCleanup</tt> won't be called, either. Thus, you have to handle all necessary cleanups in <tt>abortResume</tt>.
 
 
 
== The org.zkoss.zk.ui.util.EventInterceptor interface ==
 
It 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 the <tt>addEventInterceptor</tt> method of the <javadoc type="interface">org.zkoss.zk.ui.Desktop</javadoc> interface.
 
 
 
== The org.zkoss.zk.ui.util.WebAppInit interface ==
 
It is implemented by a listener class that will be used to initialize a ZK application.
 
 
 
When a ZK application is created, it invokes the <tt>init</tt> 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 ==
 
It 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 <tt>cleanup</tt> 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 ==
 
It 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 <tt>init</tt> 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 <tt>init</tt> method.
 
 
 
== The org.zkoss.zk.ui.util.SessionCleanup interface ==
 
It 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 <tt>cleanup</tt> 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 ==
 
It 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 <tt>init</tt> 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 <tt>init</tt> method.
 
 
 
== The org.zkoss.zk.ui.util.DesktopCleanup interface ==
 
It 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 <tt>cleanup</tt> 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 ==
 
It 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 <tt>init</tt> 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 <tt>parent</tt> argument is <tt>null</tt>.
 
 
 
A developer can prevent an execution from being created by throwing an exception in the <tt>init</tt> method.
 
 
 
== The org.zkoss.zk.ui.util.ExecutionCleanup interface ==
 
It 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 <tt>cleanup</tt> 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]
 
 
 
It is implemented by a listener class that can process the creation of ZK pages like a composer specified in the <tt>apply</tt> 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 <tt>doAfterCompose</tt> 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 <tt>getRequestPath</tt> 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.
 
 
 
<blockquote>
 
=== Richlet ===
 
 
 
A system-level composer can implement ComposerExt to handle exception such as <tt>doCatch</tt> and <tt>doFinally</tt>. However, <tt>doBeforeCompose</tt> and <tt>doBeforeComposeChildren</tt>  won't be called.
 
 
 
FullComposer is not applicable to richlets. In other words, system-level composers are called only for the root components.
 
 
 
</blockquote>
 
 
 
== The org.zkoss.zk.ui.util.URIInterceptor interface ==
 
It 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 <tt>request</tt> 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 (<tt>URIInterceptor</tt>).
 
 
 
'''Note:'''
 
 
 
# Unlike <tt>ExecutionInit</tt> and many other listeners, an instance of the registered <tt>URIInterceptor</tt> 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 ==
 
It 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 <tt>request</tt> 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 (<tt>RequestInterceptor</tt>).
 
 
 
'''Note:'''
 
 
 
# Unlike <tt>ExecutionInit</tt> and many other listeners, an instance of the registered <tt>RequestInterceptor</tt> 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 request parameters will be parsed with the proper locale and character encoding, after the <tt>request</tt> method is called. It is not recommended to call the <tt>getParameter</tt> or <tt>getParameterValues</tt> methods (of <tt>javax.servlet.ServletRequest</tt>) in this method.
 
 
 
== The org.zkoss.zk.ui.util.UiLifeCycle interface ==
 
It 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 ==
 
It 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 ==
 
It 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 <javadoc>org.zkoss.zk.ui.util.Statistic</javadoc>, which accumulates the statistic data in the memory. It is a good starting point to understand the load of your ZK application.
 

Revision as of 04:32, 31 March 2011


The listener Element


Syntax:

<listener>
    <listener-class>a_class_name</listener-class>
</listener>

Specifies the name of the class that implements one of the following interfaces. Depending on the interface(s) it implements, it will be invoked when the corresponding situation occurs.





Last Update : 2011/03/31

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