org.zkoss.zkplus.util

Class ThreadLocalListener

java.lang.Object

org.zkoss.zkplus.util.ThreadLocalListener

All Implemented Interfaces:

EventThreadCleanup, EventThreadInit, EventThreadResume

public class ThreadLocalListener
extends java.lang.Object
implements EventThreadInit, EventThreadCleanup, EventThreadResume

Listener to make sure servlet thread and ZK event thread got the same ThreadLocal values. You have to declare this listener in WEB-INF/zk.xml as follows.

        <listener>
                <description>ThreadLocal Synchronization Listener</description>
                <listener-class>org.zkoss.zkplus.util.ThreadLocalListener</listener-class>
        </listener>
 

Besides that, you have to specify what ThreadLocal variables you want to sync. They are also specified in WEB-INF/zk.xml file in the form as below.

  <preference>
    <name>ThreadLocal</name>
    <value>
                        class1=field1,field2,...;
                        class2=field1,field2,...;
                        ...
    </value>
  </preference>
 

For example, to support synchronizing Spring's thread bounded resources, you have to specify the following ThreadLocal variables:

        <preference>
                <name>ThreadLocal</name>
                <value>
                org.springframework.transaction.support.TransactionSynchronizationManager=resources,synchronizations,currentTransactionName,currentTransactionReadOnly,actualTransactionActive;
                org.springframework.orm.hibernate3.SessionFactoryUtils=deferredCloseHolder;
                org.springframework.transaction.interceptor.TransactionAspectSupport=transactionInfoHolder; <!-- ver. 2+ -->
                <!--org.springframework.transaction.interceptor.TransactionAspectSupport=currentTransactionInfo; ver. 1.28 -->
                </value>
        </preference>
 
In additions to using the application preference, you can specify it
 in the library property called zkplus.util.ThreadLocalListener.fieldsMap.
 The preference has the higher priority.
 
Another example, when you specify the Spring's bean as scope="session", you have to specify the following
 ThreadLocal variables since Spring 2.0 use RequestContextHolder to handle the bean's scope.
 

        <preference>
        <name>ThreadLocal</name>
        <value>
                org.springframework.web.context.request.RequestContextHolder=requestAttributesHolder,inheritableRequestAttributesHolder;
        </value>
 

Since:

2.4.1

Author:

henrichen

Constructor Summary

Constructors

Constructor and Description
ThreadLocalListener()

Method Summary

Methods

Modifier and Type	Method and Description
void	abortResume(Component comp, Event evt) Called when the suspended event thread is aborted.
void	afterResume(Component comp, Event evt) Called after the suspended event thread is resumed.
void	beforeResume(Component comp, Event evt) Called just before the suspended event thread is resumed.
void	cleanup(Component comp, Event evt, java.util.List errs) Cleans up the event processing thread.
void	complete(Component comp, Event evt) Called in the serlvet thread to clean up.
boolean	init(Component comp, Event evt) Initialize the event processing thread before processing the event.
void	prepare(Component comp, Event evt) Prepares the initialization at the servlet thread.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ThreadLocalListener

public ThreadLocalListener()

Method Detail

prepare

public void prepare(Component comp,
           Event evt)

Description copied from interface: EventThreadInit

Prepares the initialization at the servlet thread.

It is invoked in the servlet thread (and before EventThreadInit.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 EventThreadInit.init(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event). The event is ignored 'silently' then.

Specified by:

prepare in interface EventThreadInit

init

public boolean init(Component comp,
           Event evt)

Description copied from interface: EventThreadInit

Initialize the event processing thread before processing the event.

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

Unlike EventThreadInit.prepare(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event), it is invoked in the event processing thread (and after EventThreadInit.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>)).

Specified by:

init in interface EventThreadInit

Returns:

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

cleanup

public void cleanup(Component comp,
           Event evt,
           java.util.List errs)

Description copied from interface: EventThreadCleanup

Cleans up the event processing thread. It is called, after a event processing thread has processed an event.

If this method threw an exception and errs is empty, the exception will be propagated back to the servlet thread and then reported to the user.

Note: EventThreadCleanup.cleanup(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event, java.util.List<java.lang.Throwable>) is called first in the event processing thread, and then EventThreadCleanup.complete(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event) is called in the servlet thread. Note: EventThreadCleanup.complete(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event) of an EventThreadCleanup instance is called only if EventThreadCleanup.cleanup(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event, java.util.List<java.lang.Throwable>) called against the same instance didn't throw any exception.

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

Specified by:

cleanup in interface EventThreadCleanup

errs - a list of exceptions (java.lang.Throwable) if any exception occurred before this method is called, or null if no exception at all. Note: you can manipulate the list directly to add or clean up exceptions. For example, if exceptions are fixed correctly, you can call errs.clear() such that no error message will be displayed at the client.

complete

public void complete(Component comp,
            Event evt)

Description copied from interface: EventThreadCleanup

Called in the serlvet thread to clean up. It is called after EventThreadCleanup.cleanup(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event, java.util.List<java.lang.Throwable>) is called.

Note: EventThreadCleanup.cleanup(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event, java.util.List<java.lang.Throwable>) is called first in the event processing thread, and then EventThreadCleanup.complete(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event) is called in the servlet thread.

Specified by:

complete in interface EventThreadCleanup

beforeResume

public void beforeResume(Component comp,
                Event evt)

Description copied from interface: EventThreadResume

Called just before the suspended event thread is resumed. Unlike EventThreadResume.afterResume(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event), it executes in the main thread that resumes the suspended event processing thread.

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.

Specified by:

beforeResume in interface EventThreadResume

afterResume

public void afterResume(Component comp,
               Event evt)

Description copied from interface: EventThreadResume

Called after the suspended event thread is resumed. Unlike EventThreadResume.beforeResume(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event), it executes in the event processing thread that is resumed.

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

Specified by:

afterResume in interface EventThreadResume

abortResume

public void abortResume(Component comp,
               Event evt)

Description copied from interface: EventThreadResume

Called when the suspended event thread is aborted. It is called in the main thread (i.e., the servlet thread).

If a suspended event thread is resumed normally, EventThreadResume.beforeResume(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event) and EventThreadResume.afterResume(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event) are called. On the other hand, if it is aborted (usually caused by destroying the desktop that owns this thread), EventThreadResume.abortResume(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event) is called instead.

Note: if the suspended thread is aborted, none of EventThreadResume.beforeResume(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event), EventThreadResume.afterResume(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event), EventThreadCleanup.cleanup(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event, java.util.List<java.lang.Throwable>), and EventThreadCleanup.complete(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.event.Event) will be called. Thus, you have to do necessary cleanups in this method.

Specified by:

abortResume in interface EventThreadResume