public interface DesktopCtrl
Desktop
for implementation.
Note: applications shall never access this interface.
Modifier and Type | Method and Description |
---|---|
boolean |
activateServerPush(long timeout)
Activates the current thread for accessing this desktop by the server push.
|
void |
addComponent(Component comp)
Adds a component to this page.
|
void |
addPage(Page page)
Adds a page to this desktop.
|
void |
afterComponentAttached(Component comp,
Page page)
|
void |
afterComponentDetached(Component comp,
Page prevpage)
|
void |
afterComponentMoved(Component parent,
Component child,
Component prevparent)
|
void |
afterProcessEvent(Event event)
|
Event |
beforePostEvent(Event event)
|
Event |
beforeProcessEvent(Event event)
|
Event |
beforeSendEvent(Event event)
|
boolean |
ceaseSuspendedThread(EventProcessingThread evtthd,
java.lang.String cause)
Ceases the specified event thread.
|
void |
deactivateServerPush()
Deactivates the thread that has invoked
activateServerPush(long)
successfully. |
void |
destroy()
Called when the desktop is about to be destroyed.
|
boolean |
enableServerPush(boolean enable,
java.io.Serializable enabler)
Enable/Disable serverpush using reference counting, so that multiple enablers can
use the same serverpush and deregister whenever they want.
|
boolean |
enableServerPush(ServerPush serverpush)
Enables the server-push feature with the specified server-push
controller.
|
java.lang.Object |
getActivationLock()
Returns the lock used to activate an execution.
|
Media |
getDownloadMedia(java.lang.String medId,
boolean reserved)
Returns the media that is associated with
Desktop.getDownloadMediaURI(org.zkoss.util.media.Media, java.lang.String) , or
null if not found. |
java.lang.Object |
getLastResponse(java.lang.String reqId)
Returns the response for the last request, or null
if no response yet, or the specified request ID doesn't match
the last one (passed to
responseSent(java.lang.String, java.lang.Object) ). |
int |
getNextKey()
Returns the next available key which is unique in the whole desktop.
|
java.lang.String |
getNextUuid(Component comp)
Returns the next available UUID for a component.
|
java.lang.String |
getNextUuid(Page page)
Returns the next available UUID for a page.
|
RequestQueue |
getRequestQueue()
Returns the request queue.
|
int |
getResponseId(boolean advance)
Returns the sequence ID of the response.
|
ServerPush |
getServerPush()
Returns the server-push controller, or null if it is not enabled
yet.
|
java.util.Collection<EventProcessingThread> |
getSuspendedThreads()
Returns a collection of suspended event processing threads, or empty
if no suspended thread at all.
|
Visualizer |
getVisualizer()
Returns the visualizer associated with this desktop.
|
void |
invokeDesktopCleanups()
Invokes
DesktopCleanup.cleanup(org.zkoss.zk.ui.Desktop) for each relevant
listener registered by Desktop.addListener(java.lang.Object) . |
void |
invokeExecutionCleanups(Execution exec,
Execution parent,
java.util.List<java.lang.Throwable> errs)
Invokes
ExecutionCleanup.cleanup(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Execution, java.util.List<java.lang.Throwable>) for each relevant
listener registered by Desktop.addListener(java.lang.Object) . |
void |
invokeExecutionInits(Execution exec,
Execution parent)
Invokes
ExecutionInit.init(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Execution) for each relevant
listener registered by Desktop.addListener(java.lang.Object) . |
Component |
mapComponent(java.lang.String uuid,
Component comp)
Maps a component associated with the given UUID to this page.
|
void |
onPiggyback()
Called each time when ZK Update Engine retrieves events.
|
void |
onPiggybackListened(Component comp,
boolean listen)
Called when a component added or removed a listener for
Events.ON_PIGGYBACK . |
java.util.List<AuResponse> |
piggyResponse(java.util.Collection<AuResponse> response,
boolean reset)
Adds the responses to the so-called piggy-back queue.
|
void |
recoverDidFail(java.lang.Throwable ex)
Called when the recovering failed.
|
void |
recycle()
Called when the desktop has been recycled.
|
boolean |
removeComponent(Component comp,
boolean recycleUuidAllowed)
Removes a component to this page.
|
void |
removePage(Page page)
Removes a page from this desktop.
|
void |
responseSent(java.lang.String reqId,
java.lang.Object resInfo)
Called when ZK Update Engine has sent a response to the client.
|
boolean |
scheduledServerPush()
Returns if there is any scheduled task for server push.
|
<T extends Event> |
scheduleServerPush(EventListener<T> task,
T event)
Schedules a task to run under the server push of the given desktop asynchronously.
|
void |
service(AuRequest request,
boolean everError)
Processes an AU request.
|
void |
sessionDidActivate(Session sess)
Notification that the session, which owns this desktop,
has just been activated (a.k.a., deserialized) by the Web container.
|
void |
sessionWillPassivate(Session sess)
Notification that the session, which owns this desktop,
is about to be passivated (a.k.a., serialized) by the Web container.
|
void |
setExecution(Execution exec)
Sets the execution (used to represent a lock).
|
void |
setId(java.lang.String id)
Sets the desktop identifier.
|
void |
setResponseId(int resId)
Sets the sequence ID of the response.
|
void |
setVisualizer(Visualizer uv)
Sets the visualizer associated with is desktop.
|
RequestQueue getRequestQueue()
int getNextKey()
java.lang.String getNextUuid(Page page)
RawId
is used
(developer's responsibility to avoid conflict),
integer overflow (too many UUID in one session, which
can be considered as impossible), or a custom ID generator
(IdGenerator
) is used.java.lang.String getNextUuid(Component comp)
RawId
is used
(developer's responsibility to avoid conflict),
integer overflow (too many UUID in one session, which
can be considered as impossible), or a custom ID generator
(IdGenerator
) is used.void addComponent(Component comp)
It is used internally and developers shall not invoke it explicityly.
java.lang.InternalError
- if there is a component associated with
the same UUIDComponent mapComponent(java.lang.String uuid, Component comp)
Component.getUuid()
).
If the given component is null, the mapping of UUID is removed.
Unlike addComponent(org.zkoss.zk.ui.Component)
and removeComponent(org.zkoss.zk.ui.Component, boolean)
, this method simply replaces
the mapping if the given UUID is already mapped to the other component.
It is used internally and developers shall not invoke it explicitly.
comp
- the component to associate with the given UUID.
If not, the association (i.e., mapping) is removed.boolean removeComponent(Component comp, boolean recycleUuidAllowed)
It is used internally and developers shall not invoke it explicitly.
recycleUuidAllowed
- whether it is OK to recycle UUID.void addPage(Page page)
This is one of the only few method you could access before activating an execution.
void removePage(Page page)
NOTE: once a page is removed, you can NOT add it back. You shall just GC it.
void setId(java.lang.String id)
It is callable only if it is the recovering phase, i.e.,
ExecutionCtrl.isRecovering()
is true.
In other words, callable only in the invocation of
FailoverManager.recover(org.zkoss.zk.ui.Session, org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Desktop)
.
java.lang.IllegalStateException
- if it is NOT in recovering.void recoverDidFail(java.lang.Throwable ex)
void sessionWillPassivate(Session sess)
void sessionDidActivate(Session sess)
void destroy()
void recycle()
java.util.Collection<EventProcessingThread> getSuspendedThreads()
An event processing thread is an instance of
EventProcessingThread
Note: if you access this method NOT in an event listener for
the SAME desktop, you have to synchronize the iteration
(though the returned collection is synchronized).
Of course, it is always safe to test whether it is empty
(Collection.isEmpty()
).
//Use the following pattern IF it is not in the SAME desktop's listener
Collection c = otherDesktop.getSuspendedThreads();
if (c.isEmpty()) {
//do something accordingly
} else {
synchronized (c) {
for (Iterator it = c.iterator(); it.hasNext();) {
//...
}
}
}
boolean ceaseSuspendedThread(EventProcessingThread evtthd, java.lang.String cause)
cause
- an arbitrary text to describe the cause.
It will be the message of the thrown InterruptedException.Media getDownloadMedia(java.lang.String medId, boolean reserved)
Desktop.getDownloadMediaURI(org.zkoss.util.media.Media, java.lang.String)
, or
null if not found.
This method is used internally. Developers rarely need to access this method.
reserved
- reserved for future use.void onPiggybackListened(Component comp, boolean listen)
Events.ON_PIGGYBACK
.
The implementation usually uses it to optimize whether to
call the listener when onPiggyback()
is called.
comp
- the component that adds an listener for
Events.ON_PIGGYBACK
.
The component may or may not be a root component.listen
- whether the listener is added (or removed).void onPiggyback()
Events.ON_PIGGYBACK
).
The implementation could post events here. It should not process
event here (since event thread might be used).
Used only internally. Application developers shall not call it.
ServerPush getServerPush()
boolean enableServerPush(ServerPush serverpush)
Desktop.enableServerPush(boolean)
instead. This method allows the caller to provide a server push
for more control.
Example:
desktop.enableServerPush(new PollingServerPush(1000,6000,5));
Notice: a server push controller can be used in one desktop. It cannot be shared.
serverpush
- the server-push controller. If null,
the server-push feature is disabled (for this desktop).
Note: this method will invoke ServerPush.start(org.zkoss.zk.ui.Desktop)
, so the
caller doesn't need to do it.Desktop.enableServerPush(boolean)
boolean enableServerPush(boolean enable, java.io.Serializable enabler)
enable
- true/false enable/disable serverpushenabler
- the same reference must be used to disable againDesktopEventQueue
to enable several
eventqueues to use the same ServerPush
Event beforeSendEvent(Event event)
EventInterceptor.beforeSendEvent(org.zkoss.zk.ui.event.Event)
registered by Desktop.addListener(java.lang.Object)
.
Note: it invokes
Configuration.beforeSendEvent(org.zkoss.zk.ui.event.Event)
automatically.
Event beforePostEvent(Event event)
EventInterceptor.beforePostEvent(org.zkoss.zk.ui.event.Event)
registered by Desktop.addListener(java.lang.Object)
.
Note: it invokes
Configuration.beforePostEvent(org.zkoss.zk.ui.event.Event)
automatically.
Event beforeProcessEvent(Event event) throws java.lang.Exception
EventInterceptor.beforeProcessEvent(org.zkoss.zk.ui.event.Event)
registered by Desktop.addListener(java.lang.Object)
.
Note: it invokes
Configuration.beforeProcessEvent(org.zkoss.zk.ui.event.Event)
automatically.
java.lang.Exception
void afterProcessEvent(Event event) throws java.lang.Exception
EventInterceptor.afterProcessEvent(org.zkoss.zk.ui.event.Event)
registered by Desktop.addListener(java.lang.Object)
.
Note: it invokes
Configuration.afterProcessEvent(org.zkoss.zk.ui.event.Event)
automatically.
java.lang.Exception
void invokeDesktopCleanups()
DesktopCleanup.cleanup(org.zkoss.zk.ui.Desktop)
for each relevant
listener registered by Desktop.addListener(java.lang.Object)
.
Used only internally.
It never throws an exception.
void invokeExecutionInits(Execution exec, Execution parent) throws UiException
ExecutionInit.init(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Execution)
for each relevant
listener registered by Desktop.addListener(java.lang.Object)
.
Used only internally.
exec
- the execution that is createdparent
- the previous execution, or null if no previous at allUiException
- to prevent an execution from being createdvoid invokeExecutionCleanups(Execution exec, Execution parent, java.util.List<java.lang.Throwable> errs)
ExecutionCleanup.cleanup(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Execution, java.util.List<java.lang.Throwable>)
for each relevant
listener registered by Desktop.addListener(java.lang.Object)
.
Used only internally.
It never throws an exception but logs and adds it to the errs argument, if not null.
exec
- the execution that is being destroyedparent
- the previous execution, or null if no previous at allerrs
- 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.void afterComponentMoved(Component parent, Component child, Component prevparent)
prevparent
- the previous parent. If it is the same as
comp's Component.getParent()
, comp is moved in the same parent.void responseSent(java.lang.String reqId, java.lang.Object resInfo)
reqId
- the request ID that the response is generated for.
Ignore if null.resInfo
- the response. Ignored if reqId is null.java.lang.Object getLastResponse(java.lang.String reqId)
responseSent(java.lang.String, java.lang.Object)
).
The return value is the value passed to resInfo when calling
responseSent(java.lang.String, java.lang.Object)
.
int getResponseId(boolean advance)
The range of the sequence IDs is 1~999.
advance
- whether to advance the number before returning.
If true, the ID is increased and then returned.
If false, the previous value is returnedvoid setResponseId(int resId)
It is rarely called other than in the recovering mode, i.e.,
ExecutionCtrl.isRecovering()
is true.
resId
- a value between 1 and 999.
You can reset the ID by passing a non-positive value.java.util.List<AuResponse> piggyResponse(java.util.Collection<AuResponse> response, boolean reset)
This method is useful for working thread that wants to sent the responses back to the client. A typical example is the Comet-based server push.
response
- the responses to be appended to the piggy-back queue.reset
- whether to reset the piggy-back queue after
returning the queued responses.<T extends Event> void scheduleServerPush(EventListener<T> task, T event)
Executions.schedule(org.zkoss.zk.ui.Desktop, org.zkoss.zk.ui.event.EventListener<T>, T)
.
Don't call it directly.
Like activateServerPush(long)
and deactivateServerPush()
, this method could
be called in any thread, so the implementation of this method has to be safe for concurrent access.
task
- the task to executeevent
- the event to be passed to the task (i.e., the event listener).
It could null or any instance as long as the task recognizes it.java.lang.IllegalStateException
- if the server push is not enabled.DesktopUnavailableException
- if the desktop is removed
(when activating).boolean scheduledServerPush()
boolean activateServerPush(long timeout) throws java.lang.InterruptedException
Executions.activate(org.zkoss.zk.ui.Desktop)
.
Don't call it directly.
Like scheduleServerPush(org.zkoss.zk.ui.event.EventListener<T>, T)
, this method could
be called in any thread, so it has to be safe for concurrent access.
Note: the server push must be enabled first (by use of
Desktop.enableServerPush(boolean)
).
timeout
- the maximum time to wait in milliseconds.
Ignored (i.e., never timeout) if non-positive.java.lang.IllegalStateException
- if the server push is not enabled.java.lang.InterruptedException
void deactivateServerPush()
activateServerPush(long)
successfully.
It is called by Executions.deactivate(org.zkoss.zk.ui.Desktop)
.
Don't call it directly.void service(AuRequest request, boolean everError)
To override the default processing, register an AU request service
AuService
by invoking Desktop.addListener(java.lang.Object)
.
AuService
) one-by-one, until
the first one returns true.AuRequest.getComponent()
is not null).ComponentCtrl.service(org.zkoss.zk.au.AuRequest, boolean)
to handle the service.Event.getEvent(org.zkoss.zk.au.AuRequest)
) and then posts the event
(by Events.postEvent(org.zkoss.zk.ui.event.Event)
).Notice that the registered AU request service
(AuService
) will be called, no matter
the request is targeting a component or a desktop.
And, it can 'intercept' or 'filter' it by returning false.
To send responses to the client, use
AbstractComponent.smartUpdate(java.lang.String, java.lang.Object)
,
AbstractComponent.response(org.zkoss.zk.au.AuResponse)
or Component.invalidate()
.
If you want to intercept events, you can register a listener implementing
EventInterceptor
, or overriding afterProcessEvent(org.zkoss.zk.ui.event.Event)
.
everError
- if any error ever occurred before
processing this request. In other words, indicates if the previous
request causes any exception.void setExecution(Execution exec)
Used only to implement UiEngine
.
Visualizer getVisualizer()
Used only to implement UiEngine
.
void setVisualizer(Visualizer uv)
Used only to implement UiEngine
.
java.lang.Object getActivationLock()
setVisualizer(org.zkoss.zk.ui.sys.Visualizer)
, this object returned
by this method must be locked first.
Used only to implement UiEngine
.
Copyright © 2005-2023 Potix Corporation. All Rights Reserved.