org.zkoss.zk.ui.impl
Class UiEngineImpl

java.lang.Object
  org.zkoss.zk.ui.impl.UiEngineImpl

All Implemented Interfaces:

UiEngine

public class UiEngineImpl
extends java.lang.Object
implements UiEngine

An implementation of UiEngine.

Author:

tomyeh

Constructor Summary

UiEngineImpl()

Method Summary

void	activate(Execution exec) Activates an execution such that you can access a component.
void	addInvalidate(Component comp) Invalidates a component to cause redrawing.
void	addInvalidate(Page page) Invalidates the page to cause all of its components to redraw.
void	addMoved(Component comp, Component oldparent, Page oldpg, Page newpg) Called to update (redraw) a component, when a component is moved.
void	addResponse(java.lang.String key, AuResponse response) Adds a response which will be sent to client at the end of the execution.
void	addSmartUpdate(Component comp, java.lang.String attr, java.lang.String value) Smart updates an attribute of a component.
void	addUuidChanged(Component comp, boolean addOnlyMoved) Called before changing the component's UUID.
boolean	ceaseSuspendedThread(Desktop desktop, EventProcessingThread evtthd, java.lang.String cause) Ceases the specified event thread.
Component[]	createComponents(Execution exec, PageDefinition pagedef, Page page, Component parent, java.util.Map arg) Creates components from the specified page and definition.
void	deactivate(Execution exec) Deactivates an execution, such that other threads could activate and access components.
void	desktopDestroyed(Desktop desktop) Called when a desktop is being removed.
void	execNewPage(Execution exec, PageDefinition pagedef, Page page, java.io.Writer out) Creates components specified in the given page definition.
void	execNewPage(Execution exec, Richlet richlet, Page page, java.io.Writer out) Invoke Richlet.service(org.zkoss.zk.ui.Page), when a new page is creates upon visiting a richlet.
void	execNewPage0(Execution exec, PageDefinition pagedef, Richlet richlet, Page page, java.io.Writer out) It assumes exactly one of pagedef and richlet is not null.
void	execRecover(Execution exec, FailoverManager failover) Executes the recovering.
java.util.Collection	execUpdate(Execution exec, java.util.List requests, java.lang.String reqId, java.io.Writer out) Executs an asynchronous update to a component (or page).
void	execUpdate(Execution exec, java.util.List requests, java.io.Writer out) Executs an asynchronous update to a component (or page).
java.util.Collection	getSuspendedThreads(Desktop desktop) Returns a collection of suspended event processing threads belonging to the specified desktop, or empty if no suspended thread at all.
boolean	hasSuspendedThread() Returns if any suspended event processing thread in the whole system.
void	notify(Desktop desktop, java.lang.Object mutex) Wakes up a single event processing thread for the specified desktop that is waiting on the specified object.
void	notify(java.lang.Object mutex) Wakes up a single event processing thread that is waiting on the specified object.
void	notifyAll(Desktop desktop, java.lang.Object mutex) Wakes up all event processing theads for the specified desktop that are waiting on the specified object.
void	notifyAll(java.lang.Object mutex) Wakes up all event processing thread that are waiting on the specified object.
void	popOwner() Called after a component redraws itself if it ever calls UiEngine.pushOwner(org.zkoss.zk.ui.Component).
void	pushOwner(Component comp) Called before a component redraws itself if the component might include another page.
void	response(AuResponse response, java.io.Writer out) Generates the output for the specified the response.
void	response(java.util.List responses, java.io.Writer out) Generates the output of a list of responses.
void	sendRedirect(java.lang.String uri, java.lang.String target) Sends a temporary redirect response to the client using the specified redirect location URL.
void	setAbortingReason(AbortingReason aborting) Aborts the current execution.
void	start(WebApp wapp) Starts the engine.
void	stop(WebApp wapp) Stops the engine.
void	wait(java.lang.Object mutex) Suspends the current processing of an event and wait until the other thread invokes UiEngine.notify(Object), UiEngine.notifyAll(Object), UiEngine.notify(Desktop, Object) or UiEngine.notifyAll(Desktop, Object) for the specified object.

Methods inherited from class java.lang.Object

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

Constructor Detail

UiEngineImpl

public UiEngineImpl()

Method Detail

start

public void start(WebApp wapp)

Description copied from interface: UiEngine

Starts the engine.

Specified by:

start in interface UiEngine

stop

public void stop(WebApp wapp)

Description copied from interface: UiEngine

Stops the engine. Called only if the server is about to stop.

Specified by:

stop in interface UiEngine

hasSuspendedThread

public boolean hasSuspendedThread()

Description copied from interface: UiEngine

Returns if any suspended event processing thread in the whole system.

Specified by:

hasSuspendedThread in interface UiEngine

getSuspendedThreads

public java.util.Collection getSuspendedThreads(Desktop desktop)

Description copied from interface: UiEngine

Returns a collection of suspended event processing threads belonging to the specified desktop, or empty if no suspended thread at all.

An event processing thread is an instance of EventProcessingThread

Specified by:

getSuspendedThreads in interface UiEngine

Parameters:

desktop - the desktop that the suspended event processing threads belong to (never null).

ceaseSuspendedThread

public boolean ceaseSuspendedThread(Desktop desktop,
                                    EventProcessingThread evtthd,
                                    java.lang.String cause)

Description copied from interface: UiEngine

Ceases the specified event thread.

Specified by:

ceaseSuspendedThread in interface UiEngine

Parameters:

desktop - which desktop the event thread belongs to

cause - an arbitrary text to describe the cause. It will be the message of the thrown InterruptedException.

Returns:

true if the event processing thread is ceased successfully; false if no such thread or it is not suspended.

desktopDestroyed

public void desktopDestroyed(Desktop desktop)

Description copied from interface: UiEngine

Called when a desktop is being removed.

Application developers don't need to remove pages and desktops. They are removed and cleaned up automatically.

Specified by:

desktopDestroyed in interface UiEngine

pushOwner

public void pushOwner(Component comp)

Description copied from interface: UiEngine

Called before a component redraws itself if the component might include another page.

If a new page is created, the specified component will become the owner of the new page.

Specified by:

pushOwner in interface UiEngine

popOwner

public void popOwner()

Description copied from interface: UiEngine

Called after a component redraws itself if it ever calls UiEngine.pushOwner(org.zkoss.zk.ui.Component).

Specified by:

popOwner in interface UiEngine

addInvalidate

public void addInvalidate(Page page)

Description copied from interface: UiEngine

Invalidates the page to cause all of its components to redraw.

Specified by:

addInvalidate in interface UiEngine

addInvalidate

public void addInvalidate(Component comp)

Description copied from interface: UiEngine

Invalidates a component to cause redrawing. Called when Component.invalidate() is called.

Specified by:

addInvalidate in interface UiEngine

addSmartUpdate

public void addSmartUpdate(Component comp,
                           java.lang.String attr,
                           java.lang.String value)

Description copied from interface: UiEngine

Smart updates an attribute of a component. Called when Component.smartUpdate(String,String) is called.

The second invocation of this method in the same execution with the same attr will override the previous one.

Specified by:

addSmartUpdate in interface UiEngine

addResponse

public void addResponse(java.lang.String key,
                        AuResponse response)

Description copied from interface: UiEngine

Adds a response which will be sent to client at the end of the execution. Called when Component.response(java.lang.String, org.zkoss.zk.au.AuResponse) is called.

Note: Execution.addAuResponse(java.lang.String, org.zkoss.zk.au.AuResponse) is a shortcut to this method, and it is used by application developers.

If AuResponse.getDepends() is not null, the response depends on the returned componet. In other words, the response is removed if the component is removed. If it is null, the response is component-independent.

Specified by:

addResponse in interface UiEngine

Parameters:

key - could be anything. The second invocation of this method in the same execution with the same key will override the previous one.

addMoved

public void addMoved(Component comp,
                     Component oldparent,
                     Page oldpg,
                     Page newpg)

Description copied from interface: UiEngine

Called to update (redraw) a component, when a component is moved. If a component's page or parent is changed, this method need to be called only once for the top one.

Specified by:

addMoved in interface UiEngine

oldparent - the parent before moved

oldpg - the page before moved

newpg - the page after moved

addUuidChanged

public void addUuidChanged(Component comp,
                           boolean addOnlyMoved)

Called before changing the component's UUID.

Specified by:

addUuidChanged in interface UiEngine

Parameters:

addOnlyMoved - if true, it is added only if it was moved before (see addMoved(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Page)).

execNewPage

public void execNewPage(Execution exec,
                        Richlet richlet,
                        Page page,
                        java.io.Writer out)
                 throws java.io.IOException

Description copied from interface: UiEngine

Invoke Richlet.service(org.zkoss.zk.ui.Page), when a new page is creates upon visiting a richlet.

Specified by:

execNewPage in interface UiEngine

Throws:

java.io.IOException

execNewPage

public void execNewPage(Execution exec,
                        PageDefinition pagedef,
                        Page page,
                        java.io.Writer out)
                 throws java.io.IOException

Description copied from interface: UiEngine

Creates components specified in the given page definition. Called when a new page is creates.

Specified by:

execNewPage in interface UiEngine

Throws:

java.io.IOException

execNewPage0

public void execNewPage0(Execution exec,
                         PageDefinition pagedef,
                         Richlet richlet,
                         Page page,
                         java.io.Writer out)
                  throws java.io.IOException

It assumes exactly one of pagedef and richlet is not null.

Throws:

java.io.IOException

createComponents

public Component[] createComponents(Execution exec,
                                    PageDefinition pagedef,
                                    Page page,
                                    Component parent,
                                    java.util.Map arg)

Description copied from interface: UiEngine

Creates components from the specified page and definition. It can be called when UiEngine.execNewPage(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.metainfo.PageDefinition, org.zkoss.zk.ui.Page, java.io.Writer) or UiEngine.execUpdate(org.zkoss.zk.ui.Execution, java.util.List, java.io.Writer) was called. It assumes the execution is already locked to this desktop.

Note: if both page and parent are null, the created components don't belong to any page/parent.

Specified by:

createComponents in interface UiEngine

Parameters:

exec - the execution (never null).

pagedef - the page definition (never null).

page - the page. Ignored if parent is specified (and parent's page is used).

parent - the parent component, or null if no parent compoent. If parent is specified, page is ignored.

arg - a map of parameters that is accessible by the arg variable in EL, or by Execution.getArg(). Ignored if null.

Returns:

the components being created.

sendRedirect

public void sendRedirect(java.lang.String uri,
                         java.lang.String target)

Description copied from interface: UiEngine

Sends a temporary redirect response to the client using the specified redirect location URL.

After calling this method, the caller shall end the processing immediately (by returning). All pending requests and events will be dropped.

Specified by:

sendRedirect in interface UiEngine

Parameters:

uri - the URI to redirect to, or null to reload the same page

target - the new target, or null to denote the same browser window

setAbortingReason

public void setAbortingReason(AbortingReason aborting)

Description copied from interface: UiEngine

Aborts the current execution. if not null, it means the current execution is aborting

Note: if setAbortingReason is ever set with non-null, you CANNOT set it back to null.

After call this method, you shall not keep processing the page because the rendering is dropped and the client is out-of-sync with the server.

Specified by:

setAbortingReason in interface UiEngine

Parameters:

aborting - the aborting reason.

execRecover

public void execRecover(Execution exec,
                        FailoverManager failover)

Description copied from interface: UiEngine

Executes the recovering.

Specified by:

execRecover in interface UiEngine

execUpdate

public void execUpdate(Execution exec,
                       java.util.List requests,
                       java.io.Writer out)
                throws java.io.IOException

Description copied from interface: UiEngine

Executs an asynchronous update to a component (or page). It is the same as execUpdate(exec, requests, null, out).

Note: the output must be XML and UTF-8.

Specified by:

execUpdate in interface UiEngine

requests - a list of AuRequest.

Throws:

java.io.IOException

execUpdate

public java.util.Collection execUpdate(Execution exec,
                                       java.util.List requests,
                                       java.lang.String reqId,
                                       java.io.Writer out)
                                throws java.io.IOException

Description copied from interface: UiEngine

Executs an asynchronous update to a component (or page).

Note: the output must be XML and UTF-8.

Specified by:

execUpdate in interface UiEngine

requests - a list of AuRequest.

reqId - the request ID which is used to invoke PerformanceMeter.requestCompleteAtClient(java.lang.String, org.zkoss.zk.ui.Execution, long). Ignored if null or Configuration.getPerformanceMeter() is not defined.

Returns:

a list of request IDs that have been processed completely.

Throws:

java.io.IOException

wait

public void wait(java.lang.Object mutex)
          throws java.lang.InterruptedException,
                 SuspendNotAllowedException

Description copied from interface: UiEngine

Suspends the current processing of an event and wait until the other thread invokes UiEngine.notify(Object), UiEngine.notifyAll(Object), UiEngine.notify(Desktop, Object) or UiEngine.notifyAll(Desktop, Object) for the specified object.

It can only be called when the current thread is processing an event. And, when called, the current processing is suspended and ZK continues to process the next event and finally render the result.

It is typical use to implement a modal dialog where it won't return until the modal dialog ends.

Specified by:

wait in interface UiEngine

Parameters:

mutex - any non-null object to identify what to wait, such that UiEngine.notify(Object) and UiEngine.notify(Desktop, Object) knows which object to notify.

Throws:

SuspendNotAllowedException - if there are too many suspended exceptions. Deployers can control the maximal allowed number of suspended exceptions by specifying max-suspended-thread in zk.xml, or invoking Configuration.setMaxSuspendedThreads(int).

java.lang.InterruptedException

notify

public void notify(java.lang.Object mutex)

Description copied from interface: UiEngine

Wakes up a single event processing thread that is waiting on the specified object.

Unlike UiEngine.notify(Desktop, Object), this method can be invoked only if the same desktop is locked for processing requests.

Specified by:

notify in interface UiEngine

Parameters:

mutex - any non-null object to identify what to notify. It must be same object passed to UiEngine.wait(java.lang.Object).

See Also:

UiEngine.notify(Desktop, Object), UiEngine.notifyAll(Object)

notify

public void notify(Desktop desktop,
                   java.lang.Object mutex)

Description copied from interface: UiEngine

Wakes up a single event processing thread for the specified desktop that is waiting on the specified object.

Unlike UiEngine.notify(Object), this method can be called any time. It is designed to let working threads resume an event processing thread.

Notice: if this method is NOT called in an event processing thread, the resumed thread won't execute until the next request is received. To enforce it happen, you might use the timer component (found in ZUL).

Specified by:

notify in interface UiEngine

Parameters:

desktop - the desktop which the suspended thread is processing. It must be the same desktop of the suspended thread.

mutex - any non-null object to identify what to notify. It must be same object passed to UiEngine.wait(java.lang.Object).

See Also:

UiEngine.notify(Object), UiEngine.notifyAll(Desktop, Object)

notifyAll

public void notifyAll(java.lang.Object mutex)

Description copied from interface: UiEngine

Wakes up all event processing thread that are waiting on the specified object.

Unlike UiEngine.notify(Desktop, Object), this method can be invoked only if the same desktop is locked for processing requests.

Specified by:

notifyAll in interface UiEngine

Parameters:

mutex - any non-null object to identify what to notify. It must be same object passed to UiEngine.wait(java.lang.Object).

See Also:

UiEngine.notify(Desktop, Object), UiEngine.notifyAll(Object)

notifyAll

public void notifyAll(Desktop desktop,
                      java.lang.Object mutex)

Description copied from interface: UiEngine

Wakes up all event processing theads for the specified desktop that are waiting on the specified object.

Unlike UiEngine.notifyAll(Object), this method can be called any time. It is designed to let working threads resume an event processing thread.

If this method is NOT called in an event processing thread, the resumed thread won't execute until the next request is received. To enforce it happen, you might use the timer component (found in ZUL).

Specified by:

notifyAll in interface UiEngine

Parameters:

desktop - the desktop which the suspended thread is processing. It must be the same desktop of the suspended thread.

mutex - any non-null object to identify what to notify. It must be same object passed to UiEngine.wait(java.lang.Object).

See Also:

UiEngine.notify(Object), UiEngine.notifyAll(Desktop, Object)

response

public void response(AuResponse response,
                     java.io.Writer out)
              throws java.io.IOException

Description copied from interface: UiEngine

Generates the output for the specified the response.

Note: the output must be XML and UTF-8.

Specified by:

response in interface UiEngine

Throws:

java.io.IOException

response

public void response(java.util.List responses,
                     java.io.Writer out)
              throws java.io.IOException

Description copied from interface: UiEngine

Generates the output of a list of responses.

Note: the output must be XML and UTF-8.

Specified by:

response in interface UiEngine

Throws:

java.io.IOException

activate

public void activate(Execution exec)

Description copied from interface: UiEngine

Activates an execution such that you can access a component. You must call UiEngine.deactivate(org.zkoss.zk.ui.Execution) in the finally clause.

Note: you RARELY need to invoke this method because UiEngine.execNewPage(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.metainfo.PageDefinition, org.zkoss.zk.ui.Page, java.io.Writer) and UiEngine.execUpdate(org.zkoss.zk.ui.Execution, java.util.List, java.io.Writer) will activate and deactivate automatically.

Note: this method can be called only when processing a client request (e.g., HTTP) other than creating a new page and processing async-update.

Also, even if you use this method to grant the right to access components of the specified page, don't post events, create, remove, invalidate and do any smart updates. In other words, READ ONLY.

Specified by:

activate in interface UiEngine

deactivate

public void deactivate(Execution exec)

Description copied from interface: UiEngine

Deactivates an execution, such that other threads could activate and access components.

Specified by:

deactivate in interface UiEngine