org.zkoss.zk.ui.sys
Interface UiEngine

All Known Implementing Classes:

UiEngineImpl

public interface UiEngine

UI engine is reponsible to process requests from the client, sends the response back to the client with the assistent of ExecutionCtrl.

ExecutionCtrl encapsulates protocol-dependent codes, such that UiEngine works independent of any protocol (such as HTTP).

Note: each application (a ServletContext in HTTP) has its own UI Engine (Singleton per app).

Author:

tomyeh

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, DeferredValue value) Smart updates an attribute of a component with a deferred value.
void	addSmartUpdate(Component comp, java.lang.String attr, java.lang.Object[] values) Smart updates an attribute of a component with an array of values.
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.
void	beginUpdate(Execution exec) Activates and prepare for asynchronous update
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	endUpdate(Execution exec, AuWriter out) Executes posted events, deactive and ends the asynchronous update.
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	execRecover(Execution exec, FailoverManager failover) Executes the recovering.
void	execUpdate(Execution exec, java.util.List requests, AuWriter out) Executs an asynchronous update to a component (or page).
java.lang.String	getNativeContent(Component comp, java.util.List children, Native.Helper helper) Retrieve the native content for a property of the specified component.
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.
boolean	isInvalidated(Component comp) Returns if this component needs to be redrawn.
boolean	isRequestDuplicate(Execution exec, AuWriter out) Checks whether the request is duplicated.
void	notify(Desktop desktop, java.lang.Object obj) Wakes up a single event processing thread for the specified desktop that is waiting on the specified object.
void	notify(java.lang.Object obj) Wakes up a single event processing thread that is waiting on the specified object.
void	notifyAll(Desktop desktop, java.lang.Object obj) Wakes up all event processing theads for the specified desktop that are waiting on the specified object.
void	notifyAll(java.lang.Object obj) 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 pushOwner(org.zkoss.zk.ui.Component).
void	pushOwner(Component comp) Called before a component redraws itself if the component might include another page.
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 obj) Suspends the current processing of an event and wait until the other thread invokes notify(Object), notifyAll(Object), notify(Desktop, Object) or notifyAll(Desktop, Object) for the specified object.

Method Detail

start

void start(WebApp wapp)

Starts the engine.

stop

void stop(WebApp wapp)

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

desktopDestroyed

void desktopDestroyed(Desktop desktop)

Called when a desktop is being removed.

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

pushOwner

void pushOwner(Component comp)

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.

popOwner

void popOwner()

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

isInvalidated

boolean isInvalidated(Component comp)

Returns if this component needs to be redrawn.

Note:

1. It always returns true if the current execution is not an asynchroous update.
2. If its parent is invalidated, this component will be redrawn too, but this method returns false since addInvalidate(Component) was not called against this component.

Since:

3.0.5

addInvalidate

void addInvalidate(Page page)

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

addInvalidate

void addInvalidate(Component comp)

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

addSmartUpdate

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

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

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

addSmartUpdate

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

Smart updates an attribute of a component with a deferred value. A deferred value is used to encapsulate a value that shall be retrieved only in the rendering phase.

Since:

3.0.1

See Also:

ComponentCtrl.smartUpdateDeferred(String, DeferredValue)

addSmartUpdate

void addSmartUpdate(Component comp,
                    java.lang.String attr,
                    java.lang.Object[] values)

Smart updates an attribute of a component with an array of values. Each element of values must be an instance of String or DeferredValue.

Since:

3.0.5

See Also:

ComponentCtrl.smartUpdateValues(String, Object[])

addResponse

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

Adds a response which will be sent to client at the end of the execution. Called when ComponentCtrl.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.

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

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

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.

Parameters:

oldparent - the parent before moved

oldpg - the page before moved

newpg - the page after moved

addUuidChanged

void addUuidChanged(Component comp,
                    boolean addOnlyMoved)

Called before changing the component's UUID.

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

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

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

Throws:

java.io.IOException

execNewPage

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

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

Throws:

java.io.IOException

execUpdate

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

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.

Parameters:

requests - a list of AuRequest.

Throws:

java.io.IOException

execRecover

void execRecover(Execution exec,
                 FailoverManager failover)

Executes the recovering.

createComponents

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

Creates components from the specified page and definition. It can be called when execNewPage(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.metainfo.PageDefinition, org.zkoss.zk.ui.Page, java.io.Writer) or execUpdate(org.zkoss.zk.ui.Execution, java.util.List, org.zkoss.zk.au.AuWriter) 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.

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). If both page and parent are null, the created components won't belong to any page.

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

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

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.

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

void setAbortingReason(AbortingReason aborting)

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.

Parameters:

aborting - the aborting reason.

wait

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

Suspends the current processing of an event and wait until the other thread invokes notify(Object), notifyAll(Object), notify(Desktop, Object) or 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.

Parameters:

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

Throws:

UiException - if it is called not during event processing.

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

void notify(java.lang.Object obj)

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

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

Parameters:

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

Throws:

UiException - if it is called not during event processing.

See Also:

notify(Desktop, Object), notifyAll(Object)

notifyAll

void notifyAll(java.lang.Object obj)

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

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

Parameters:

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

Throws:

UiException - if it is called not during event processing.

See Also:

notify(Desktop, Object), notifyAll(Object)

notify

void notify(Desktop desktop,
            java.lang.Object obj)

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

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

Parameters:

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

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

See Also:

notify(Object), notifyAll(Desktop, Object)

notifyAll

void notifyAll(Desktop desktop,
               java.lang.Object obj)

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

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

Parameters:

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

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

See Also:

notify(Object), notifyAll(Desktop, Object)

activate

void activate(Execution exec)

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

Note: you RARELY need to invoke this method because execNewPage(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.metainfo.PageDefinition, org.zkoss.zk.ui.Page, java.io.Writer) and execUpdate(org.zkoss.zk.ui.Execution, java.util.List, org.zkoss.zk.au.AuWriter) 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.

deactivate

void deactivate(Execution exec)

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

isRequestDuplicate

boolean isRequestDuplicate(Execution exec,
                           AuWriter out)
                           throws java.io.IOException

Checks whether the request is duplicated. Due to HTTP (and ZK Client Engine), the same request might be sent multiple times. And, this method is used to handle the duplicate request.

It must be called before beginUpdate(org.zkoss.zk.ui.Execution) and endUpdate(org.zkoss.zk.ui.Execution, org.zkoss.zk.au.AuWriter). And, you shall not call beginUpdate(org.zkoss.zk.ui.Execution) and endUpdate(org.zkoss.zk.ui.Execution, org.zkoss.zk.au.AuWriter), if this method return true.

Returns:

whether the request is duplicated. If duplicate (true), the response is generated automatically and no more processing is required.

Throws:

java.io.IOException

Since:

3.5.0

beginUpdate

void beginUpdate(Execution exec)

Activates and prepare for asynchronous update

Since:

3.5.0

endUpdate

void endUpdate(Execution exec,
               AuWriter out)
               throws java.io.IOException

Executes posted events, deactive and ends the asynchronous update.

Parameters:

out - the AU writer to generate the responses to; never null.

Throws:

java.io.IOException

Since:

3.5.0

getNativeContent

java.lang.String getNativeContent(Component comp,
                                  java.util.List children,
                                  Native.Helper helper)

Retrieve the native content for a property of the specified component. The native content is a value of a property that is represented by a XML fragment (actually NativeInfo).

Example:

<html>
 <attribute name="content">
  <br/>
 </attribute>
</html>

Parameters:

comp - the component that the native content will be assigned to. It is the object that the self variable is assigned when evaluating EL expressions.

children - a list of NativeInfo, TextInfo and others. This method evaluates them one-by-one and returns the result which is the value that will be assigned.

helper - the helper used to generate the content.

Since:

3.5.0

See Also:

Property

hasSuspendedThread

boolean hasSuspendedThread()

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

getSuspendedThreads

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.

An event processing thread is an instance of EventProcessingThread

Parameters:

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

ceaseSuspendedThread

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

Ceases the specified event thread.

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.