Interface UiEngine
-
- All Known Implementing Classes:
UiEngineImpl
public interface UiEngine
UI engine is responsible to process requests from the client, sends the response back to the client with the assistance ofExecutionCtrl
.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
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
activate(Execution exec)
Activates an execution such that you can access a component.boolean
activate(Execution exec, int timeout)
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
addResponse(java.lang.String key, AuResponse response, int priority)
Adds a response with the given priority.void
addResponse(AuResponse response)
Adds a response directly by usingAuResponse.getOverrideKey()
as the override key.void
addSmartUpdate(Component comp, java.lang.String attr, java.lang.Object value, boolean append)
Smart-updates a property of the peer widget.void
addSmartUpdate(Component comp, java.lang.String attr, java.lang.Object value, int priority)
Adds a smart update that will be executed at the given priority.void
addUuidChanged(Component comp)
Called before changing the component's UUID.void
beginUpdate(Execution exec)
Activates and prepare for asynchronous updateboolean
ceaseSuspendedThread(Desktop desktop, EventProcessingThread evtthd, java.lang.String cause)
Ceases the specified event thread.void
clearSmartUpdate(Component comp)
Clears all existing smart updates that belong to the given component.void
closeUpdate(java.lang.Object ctx)
Deactivates the execution and cleans up.Component[]
createComponents(Execution exec, PageDefinition pagedef, Page page, Component parent, Component insertBefore, VariableResolver resolver, 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.boolean
disableClientUpdate(Component comp, boolean disable)
Sets whether to disable the update of the client widget.void
endUpdate(Execution exec)
Executes posted events, deactivate 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)
InvokeRichlet.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<AuRequest> requests, AuWriter out)
Executes an asynchronous update to a component (or page).JSONArray
finishUpdate(java.lang.Object ctx)
Finishes the update and returns the result in an array of JSON object.JSONArray
finishUpdate(java.lang.Object ctx, java.util.List<java.lang.Throwable> errs)
Finishes the update and returns the result in an array of JSON object.java.lang.String
getNativeContent(Component comp, java.util.List<NodeInfo> children, Native.Helper helper)
Retrieve the native content for a property of the specified component.java.util.Collection<EventProcessingThread>
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.void
notify(java.lang.Object obj)
Wakes up a single event processing thread that is waiting on the specified object.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
notifyAll(java.lang.Object obj)
Wakes up all event processing thread that are waiting on the specified object.void
notifyAll(Desktop desktop, java.lang.Object obj)
Wakes up all event processing threads for the specified desktop that are waiting on the specified object.void
recycleDesktop(Execution exec, Page page, java.io.Writer out)
Reuse the desktop and generate the output.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.Component
setOwner(Component comp)
Called before a component redraws itself if the component might include another page.void
start(WebApp wapp)
Starts the engine.java.lang.Object
startUpdate(Execution exec)
Activates an execution that will allow developers to update the state of components.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 invokesnotify(Object)
,notifyAll(Object)
,notify(Desktop, Object)
ornotifyAll(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.
-
setOwner
Component setOwner(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.
It must reset the owner in the finally clause.
old = ue.setOwner(this); try{ ... } finally { ue.setOwner(old); }
Since 5.0.6, the owner must implement
Includer
.- Returns:
- the previous owner
- Since:
- 5.0.0
-
isInvalidated
boolean isInvalidated(Component comp)
Returns if this component needs to be redrawn.Note:
- It always returns true if the current execution is not an asynchronous update.
- 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 whenComponent.invalidate()
is called.
-
addSmartUpdate
void addSmartUpdate(Component comp, java.lang.String attr, java.lang.Object value, boolean append)
Smart-updates a property of the peer widget.- Parameters:
append
- whether to append the updates of properties with the same name. If false, only the last value of the same property will be sent to the client.- Since:
- 5.0.2
-
addSmartUpdate
void addSmartUpdate(Component comp, java.lang.String attr, java.lang.Object value, int priority)
Adds a smart update that will be executed at the given priority. The higher priority, the earlier the update is executed. IfaddSmartUpdate(Component, String, Object, boolean)
is invoked, the priority is assumed to 0.If the priority is the same, the update is executed in the order of first-in-first out. You rarely need to control the sequence, unless the update is used to instantiate client-side widgets that other updates might depend on. In this case, it is suggested to specify the priority as 10000 (and not to use priority higher than 10000 for other situation).
- Since:
- 6.0.0
-
clearSmartUpdate
void clearSmartUpdate(Component comp)
Clears all existing smart updates that belong to the given component.- Since:
- 10.0.0
-
addResponse
void addResponse(AuResponse response)
Adds a response directly by usingAuResponse.getOverrideKey()
as the override key. In other words, it is the same asaddResponse(resposne.getOverrideKey(), response)
If the response is component-dependent,
AuResponse.getDepends()
must return a component. And, if the component is removed, the response is removed, too.- Since:
- 5.0.2
- See Also:
addResponse(String, AuResponse)
-
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 byAbstractComponent.response(org.zkoss.zk.au.AuResponse)
.Note:
Execution.addAuResponse(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 component. 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. If null, the response is appended. If not null, the second invocation of this method in the same execution with the same key and the same depends (AuResponse.getDepends()
) will override the previous one.- See Also:
addResponse(AuResponse)
-
addResponse
void addResponse(java.lang.String key, AuResponse response, int priority)
Adds a response with the given priority. The higher priority, the earlier the update is executed. The priority ofaddResponse(String, AuResponse)
andaddResponse(AuResponse)
is assumed to be 0.If the priority is the same, the update is executed in the order of first-in-first out.
- Since:
- 6.0.1
-
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 movedoldpg
- the page before movednewpg
- the page after moved
-
addUuidChanged
void addUuidChanged(Component comp)
Called before changing the component's UUID.- Since:
- 5.0.3
-
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
InvokeRichlet.service(org.zkoss.zk.ui.Page)
, when a new page is creates upon visiting a richlet.- Throws:
java.io.IOException
-
recycleDesktop
void recycleDesktop(Execution exec, Page page, java.io.Writer out) throws java.io.IOException
Reuse the desktop and generate the output.- Throws:
java.io.IOException
- Since:
- 5.0.0
-
execUpdate
void execUpdate(Execution exec, java.util.List<AuRequest> requests, AuWriter out) throws java.io.IOException
Executes 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 ofAuRequest
.- Throws:
java.io.IOException
-
startUpdate
java.lang.Object startUpdate(Execution exec) throws java.io.IOException
Activates an execution that will allow developers to update the state of components.It is designed to implement
Bridge
.- Returns:
- a context that shall be passed to
finishUpdate(java.lang.Object)
. - Throws:
java.io.IOException
- Since:
- 5.0.5
- See Also:
finishUpdate(java.lang.Object)
,closeUpdate(java.lang.Object)
-
finishUpdate
JSONArray finishUpdate(java.lang.Object ctx) throws java.io.IOException
Finishes the update and returns the result in an array of JSON object. Notice it does not deactivate the execution. Rather, the caller has to invokecloseUpdate(java.lang.Object)
.It is designed to implement
Bridge
.- Parameters:
ctx
- the context returned by the previous call tostartUpdate(org.zkoss.zk.ui.Execution)
- Throws:
java.io.IOException
- Since:
- 5.0.5
- See Also:
startUpdate(org.zkoss.zk.ui.Execution)
,closeUpdate(java.lang.Object)
-
finishUpdate
JSONArray finishUpdate(java.lang.Object ctx, java.util.List<java.lang.Throwable> errs) throws java.io.IOException
Finishes the update and returns the result in an array of JSON object. Notice it does not deactivate the execution. Rather, the caller has to invokecloseUpdate(java.lang.Object)
.It is designed to implement
Bridge
.- Parameters:
ctx
- the context returned by the previous call tostartUpdate(org.zkoss.zk.ui.Execution)
errs
- the collection of errors if any.- Throws:
java.io.IOException
- Since:
- 10.0.0
- See Also:
finishUpdate(Object)
-
closeUpdate
void closeUpdate(java.lang.Object ctx) throws java.io.IOException
Deactivates the execution and cleans up.It is designed to implement
Bridge
.- Throws:
java.io.IOException
- Since:
- 5.0.5
- See Also:
startUpdate(org.zkoss.zk.ui.Execution)
,finishUpdate(java.lang.Object)
-
execRecover
void execRecover(Execution exec, FailoverManager failover)
Executes the recovering.
-
createComponents
Component[] createComponents(Execution exec, PageDefinition pagedef, Page page, Component parent, Component insertBefore, VariableResolver resolver, java.util.Map<?,?> arg)
Creates components from the specified page and definition. It can be called whenexecNewPage(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.metainfo.PageDefinition, org.zkoss.zk.ui.Page, java.io.Writer)
orexecUpdate(org.zkoss.zk.ui.Execution, java.util.List<org.zkoss.zk.au.AuRequest>, 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 not null (parent's page will be 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 component. If parent is specified, page is ignored.insertBefore
- the sibling component that new components will be inserted before. Ignored if null (i.e., append as last children).resolver
- the variable resolver used to resolve variables. Ignored if null.arg
- a map of parameters that is accessible by the arg variable in EL, or byExecution.getArg()
. Ignored if null.- Returns:
- the components being created.
- Since:
- 6.0.0
-
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 pagetarget
- 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 abortingNote: 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 invokesnotify(Object)
,notifyAll(Object)
,notify(Desktop, Object)
ornotifyAll(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 thatnotify(Object)
andnotify(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 specifyingmax-suspended-thread
inzk.xml
, or invokingConfiguration.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 towait(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 towait(java.lang.Object)
.- See Also:
notify(Object)
,notifyAll(Desktop, 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 towait(java.lang.Object)
.- Throws:
UiException
- if it is called not during event processing.- See Also:
notify(Desktop, Object)
,notifyAll(Object)
-
notifyAll
void notifyAll(Desktop desktop, java.lang.Object obj)
Wakes up all event processing threads 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 towait(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 calldeactivate(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)
andexecUpdate(org.zkoss.zk.ui.Execution, java.util.List<org.zkoss.zk.au.AuRequest>, 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.
-
activate
boolean activate(Execution exec, int timeout)
Activates an execution such that you can access a component. Unlikeactivate(Execution)
, you could specify an amount of time (timeout), and it returns false if it takes longer than the given amount of time before granted.- Parameters:
timeout
- the number of milliseconds to wait before giving up. It is ignored if negative, i.e., it waits until granted if negative.- Returns:
- whether the activation succeeds
- Since:
- 5.0.6
-
deactivate
void deactivate(Execution exec)
Deactivates an execution, such that other threads could activate and access components.
-
beginUpdate
void beginUpdate(Execution exec)
Activates and prepare for asynchronous update- Since:
- 3.5.0
-
endUpdate
void endUpdate(Execution exec) throws java.io.IOException
Executes posted events, deactivate and ends the asynchronous update.- Throws:
java.io.IOException
- Since:
- 5.0.0
-
getNativeContent
java.lang.String getNativeContent(Component comp, java.util.List<NodeInfo> 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 (actuallyNativeInfo
).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 ofNativeInfo
,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<EventProcessingThread> 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 tocause
- 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.
-
disableClientUpdate
boolean disableClientUpdate(Component comp, boolean disable)
Sets whether to disable the update of the client widget. By default, if a component is attached to a page, modifications that change the visual representation will be sent to the client to ensure the consistency.- Returns:
- whether it has been disabled before this invocation, i.e., the previous disable status
- Since:
- 3.6.2
-
-