org.zkoss.zk.ui.impl
Class DesktopImpl

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

All Implemented Interfaces:

java.io.Serializable, Desktop, Scope, DesktopCtrl

public class DesktopImpl
extends java.lang.Object
implements Desktop, DesktopCtrl, java.io.Serializable

The implementation of Desktop.

Note: though DesktopImpl is serializable, it is designed to work with Web container to enable the serialization of sessions. It is not suggested to serialize and desrialize it directly since many fields might be lost.

On the other hand, it is OK to serialize and deserialize Component.

Author:

tomyeh

See Also:

Serialized Form

Constructor Summary

DesktopImpl(WebApp wapp, java.lang.String updateURI, java.lang.String path, java.lang.String deviceType, java.lang.Object request)

Method Summary

boolean	activateServerPush(long timeout) Activates the server push.
void	addComponent(Component comp) Adds a component to this page.
void	addEventInterceptor(EventInterceptor ei) Deprecated. As of release 3.0.6, replaced by addListener(java.lang.Object).
void	addListener(java.lang.Object listener) Adds a listener.
void	addPage(Page page) Adds a page to this desktop.
void	afterComponentAttached(Component comp, Page page) Invokes UiLifeCycle.afterComponentAttached(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Page).
void	afterComponentDetached(Component comp, Page prevpage) Invokes UiLifeCycle.afterComponentDetached(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Page).
void	afterComponentMoved(Component parent, Component child, Component prevparent) Invokes UiLifeCycle.afterComponentMoved(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component).
void	afterProcessEvent(Event event) Invokes EventInterceptor.afterProcessEvent(org.zkoss.zk.ui.event.Event) registered by Desktop.addListener(java.lang.Object).
Event	beforePostEvent(Event event) Invokes EventInterceptor.beforePostEvent(org.zkoss.zk.ui.event.Event) registered by Desktop.addListener(java.lang.Object).
Event	beforeProcessEvent(Event event) Invokes EventInterceptor.beforeProcessEvent(org.zkoss.zk.ui.event.Event) registered by Desktop.addListener(java.lang.Object).
Event	beforeSendEvent(Event event) Invokes EventInterceptor.beforeSendEvent(org.zkoss.zk.ui.event.Event) registered by Desktop.addListener(java.lang.Object).
boolean	ceaseSuspendedThread(EventProcessingThread evtthd, java.lang.String cause) Ceases the specified event thread.
void	deactivateServerPush() Deactivates the server push.
void	destroy() Called when the desktop is about to be destroyed.
boolean	enableServerPush(boolean enable) Enables or disables the server-push feature.
boolean	enableServerPush(ServerPush serverpush) Enables the server-push feature with the specified server-push controller.
java.lang.Object	getAttribute(java.lang.String name) Returns the value of the specified custom attribute associated with the desktop.
java.util.Map	getAttributes() Returns all custom attributes associated with this desktop.
java.lang.String	getBookmark() Returns the current bookmark (never null).
Component	getComponentByUuid(java.lang.String uuid) Returns the component of the specified UUID (Component.getUuid()).
Component	getComponentByUuidIfAny(java.lang.String uuid) Returns the component of the specified UUID (Component.getUuid()), or null if not found.
java.util.Collection	getComponents() Returns all components contained in this desktop.
java.lang.String	getCurrentDirectory() Returns the current directory (never null).
Device	getDevice() Returns the device that is associated with this desktop.
java.lang.String	getDeviceType() Returns the device type that this desktop belongs to.
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.String	getDownloadMediaURI(Media media, java.lang.String pathInfo) Returns URI for a media that is used to download to the client.
java.lang.String	getDynamicMediaURI(Component comp, java.lang.String pathInfo) Returns URI for a dynamic generated media associated with a component.
Execution	getExecution() Returns the execution, or null if this desktop is not under seving any execution (aka., not locked).
java.lang.String	getId() Returns ID of this desktop.
java.lang.Object	getLastResponse(java.lang.String channel, java.lang.String reqId) Returns the information of response for the last request, or null if no response yet, or the specified request ID doesn't match the last one (passed to DesktopCtrl.responseSent(java.lang.String, java.lang.String, java.lang.Object)).
int	getNextKey() Returns the next available key which is unique in the whole desktop.
java.lang.String	getNextUuid() Returns the next available UUID for a component.
Page	getPage(java.lang.String pageId) Returns the page of the specified ID.
Page	getPageIfAny(java.lang.String pageId) Returns the page of the specified ID, or null if no such page.
java.util.Collection	getPages() Returns a readonly collection of all Page in this desktop.
java.lang.String	getRequestPath() Returns the path of the request that causes this desktop to be created, or "" if not available.
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.
Session	getSession() Returns the session of this desktop.
java.util.Collection	getSuspendedThreads() Returns a collection of suspended event processing threads, or empty if no suspended thread at all.
java.lang.String	getUpdateURI(java.lang.String pathInfo) Returns the URI for asynchronous update.
WebApp	getWebApp() Returns the Web application this desktop belongs to.
boolean	hasPage(java.lang.String pageId) Returns whether a page exists.
void	invalidate() Invalidates the 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 errs) Invokes ExecutionCleanup.cleanup(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Execution, java.util.List) 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).
boolean	isAlive() Returns whether the desktop is still alive.
boolean	isServerPushEnabled() Returns whether the server-push feature is enabled for this desktop.
protected RequestQueue	newRequestQueue() Creates the request queue.
void	onPiggyback() Called each time ZK Update Engine processes all events.
void	onPiggybackListened(Component comp, boolean listen) Called when a component added or removed a listener for Events.ON_PIGGYBACK.
void	recoverDidFail(java.lang.Throwable ex) Called when the recoving failed.
java.lang.Object	removeAttribute(java.lang.String name) Removes the specified custom attribute associated with the desktop.
void	removeComponent(Component comp) Removes a component to this page.
boolean	removeEventInterceptor(EventInterceptor ei) Deprecated. As of release 3.0.6, replaced by removeListener(java.lang.Object).
boolean	removeListener(java.lang.Object listener) Removes a listener.
void	removePage(Page page) Removes a page from this desktop.
void	responseSent(java.lang.String channel, java.lang.String reqId, java.lang.Object response) Called when ZK Update Engine has sent a response to the client.
void	sessionDidActivate(Session sess) Notification that the session, which owns this desktop, has just been activated (aka., deserialized) by the Web container.
void	sessionWillPassivate(Session sess) Notification that the session, which owns this desktop, is about to be passivated (aka., serialized) by the Web container.
java.lang.Object	setAttribute(java.lang.String name, java.lang.Object value) Sets the value of the specified custom attribute associated with the desktop.
void	setBookmark(java.lang.String name) Sets a bookmark to this desktop.
void	setBookmarkByClient(java.lang.String name) Sets the bookmark when receiving the onBookmarkChange command from the client.
void	setCurrentDirectory(java.lang.String dir) Sets the current directory.
void	setDeviceType(java.lang.String deviceType) Sets the device type that this desktop belongs to.
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	setServerPushDelay(int min, int max, int factor) Sets the delay between each polling.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

DesktopImpl

public DesktopImpl(WebApp wapp,
                   java.lang.String updateURI,
                   java.lang.String path,
                   java.lang.String deviceType,
                   java.lang.Object request)

Parameters:

updateURI - the URI to access the update engine (no expression allowed). Note: it is NOT encoded yet.

path - the path that causes this desktop to create. If null or empty is specified, it means not available.

deviceType - the device type. If null or empty is specified, "ajax" is assumed.

Since:

3.0.1

Method Detail

getId

public java.lang.String getId()

Description copied from interface: Desktop

Returns ID of this desktop. It is unique in the whole session.

Specified by:

getId in interface Desktop

newRequestQueue

protected RequestQueue newRequestQueue()

Creates the request queue. It is called when the desktop is initialized.

You may override it to provide your implementation of RequestQueue to control how to optimize the AU requests.

Default: creates an instance from RequestQueueImpl;

Since:

2.4.0

getDeviceType

public java.lang.String getDeviceType()

Description copied from interface: Desktop

Returns the device type that this desktop belongs to.

A device type identifies the type of a client. For example, "ajax" represents the Web browsers with Ajax support, while "mil" represents clients that supports Mobile Interactive markup Language (on Limited Connected Device, such as mobile phones).

A desktop can use the languages belonging to the same device type. See also LanguageDefinition.getDeviceType().

A component can be added to a desktop only if they belong to the same device type.

Default: depends on the extension of the resource path, "ajax" if the path or extension not available. If Richlet is used, its language definition's device type is assumed.

Specified by:

getDeviceType in interface Desktop

getDevice

public Device getDevice()

Description copied from interface: Desktop

Returns the device that is associated with this desktop.

Note: the device is shared by all desktops of the same device type.

Specified by:

getDevice in interface Desktop

setDeviceType

public void setDeviceType(java.lang.String deviceType)

Description copied from interface: Desktop

Sets the device type that this desktop belongs to.

Note: you can change the device type only before any component is attached to a page of the desktop. In other words, you can set the device type only at the initialization stage.

If the device type is changed, any device allocated for this desktop (Desktop.getDevice()) will be dropped and recreated at the next invocation to Desktop.getDevice().

Specified by:

setDeviceType in interface Desktop

getExecution

public Execution getExecution()

Description copied from interface: Desktop

Returns the execution, or null if this desktop is not under seving any execution (aka., not locked).

Specified by:

getExecution in interface Desktop

getSession

public final Session getSession()

Description copied from interface: Desktop

Returns the session of this desktop.

Specified by:

getSession in interface Desktop

getUpdateURI

public java.lang.String getUpdateURI(java.lang.String pathInfo)

Description copied from interface: Desktop

Returns the URI for asynchronous update.

You rarely need this method unless for implementing special components, such as file upload.

Specified by:

getUpdateURI in interface Desktop

Parameters:

pathInfo - the path to append to the returned URI, or null to ignore

getDynamicMediaURI

public java.lang.String getDynamicMediaURI(Component comp,
                                           java.lang.String pathInfo)

Description copied from interface: Desktop

Returns URI for a dynamic generated media associated with a component. ZK Update Engine will then invoke invoke DynamicMedia.getMedia(java.lang.String) to response.

Note: to use with this method, DynamicMedia must be implemented as part of the object returned by ComponentCtrl.getExtraCtrl().

Used mainly for component implementation.

Specified by:

getDynamicMediaURI in interface Desktop

getDownloadMediaURI

public java.lang.String getDownloadMediaURI(Media media,
                                            java.lang.String pathInfo)

Description copied from interface: Desktop

Returns URI for a media that is used to download to the client. The client will open a Save As dialog to save the specified file.

Note: once called, the media belongs to desktop and it is purged automatically. Thus, don't access it again after calling this method.

Specified by:

getDownloadMediaURI in interface Desktop

getDownloadMedia

public Media getDownloadMedia(java.lang.String medId,
                              boolean reserved)

Description copied from interface: DesktopCtrl

Returns the media that is associated with 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.

Specified by:

getDownloadMedia in interface DesktopCtrl

reserved - reserved for future use.

Returns:

the media or null if not found.

getPage

public Page getPage(java.lang.String pageId)

Description copied from interface: Desktop

Returns the page of the specified ID.

This is one of the only few method you could access before activating an execution.

Specified by:

getPage in interface Desktop

getPageIfAny

public Page getPageIfAny(java.lang.String pageId)

Description copied from interface: Desktop

Returns the page of the specified ID, or null if no such page.

Specified by:

getPageIfAny in interface Desktop

hasPage

public boolean hasPage(java.lang.String pageId)

Description copied from interface: Desktop

Returns whether a page exists.

Specified by:

hasPage in interface Desktop

getPages

public java.util.Collection getPages()

Description copied from interface: Desktop

Returns a readonly collection of all Page in this desktop.

Specified by:

getPages in interface Desktop

getBookmark

public java.lang.String getBookmark()

Description copied from interface: Desktop

Returns the current bookmark (never null). The returned might be the same as the last call to Desktop.setBookmark(java.lang.String), because user might use BACK, FORWARD or others to change the bookmark.

Specified by:

getBookmark in interface Desktop

setBookmark

public void setBookmark(java.lang.String name)

Description copied from interface: Desktop

Sets a bookmark to this desktop. Then, when user press BACK, FORWARD or specify an URL with this bookmark, the onBookmarkChange event is sent to all pages of the desktop.

Specified by:

setBookmark in interface Desktop

getComponents

public java.util.Collection getComponents()

Description copied from interface: Desktop

Returns all components contained in this desktop.

Specified by:

getComponents in interface Desktop

getComponentByUuid

public Component getComponentByUuid(java.lang.String uuid)

Description copied from interface: Desktop

Returns the component of the specified UUID (Component.getUuid()).

Specified by:

getComponentByUuid in interface Desktop

getComponentByUuidIfAny

public Component getComponentByUuidIfAny(java.lang.String uuid)

Description copied from interface: Desktop

Returns the component of the specified UUID (Component.getUuid()), or null if not found.

Specified by:

getComponentByUuidIfAny in interface Desktop

addComponent

public void addComponent(Component comp)

Description copied from interface: DesktopCtrl

Adds a component to this page.

It is used internally and developers shall not invoke it explicityly.

Specified by:

addComponent in interface DesktopCtrl

removeComponent

public void removeComponent(Component comp)

Description copied from interface: DesktopCtrl

Removes a component to this page.

It is used internally and developers shall not invoke it explicityly.

Specified by:

removeComponent in interface DesktopCtrl

getAttributes

public java.util.Map getAttributes()

Description copied from interface: Desktop

Returns all custom attributes associated with this desktop.

Specified by:

getAttributes in interface Desktop

Specified by:

getAttributes in interface Scope

getAttribute

public java.lang.Object getAttribute(java.lang.String name)

Description copied from interface: Desktop

Returns the value of the specified custom attribute associated with the desktop.

Specified by:

getAttribute in interface Desktop

Specified by:

getAttribute in interface Scope

setAttribute

public java.lang.Object setAttribute(java.lang.String name,
                                     java.lang.Object value)

Description copied from interface: Desktop

Sets the value of the specified custom attribute associated with the desktop.

Specified by:

setAttribute in interface Desktop

removeAttribute

public java.lang.Object removeAttribute(java.lang.String name)

Description copied from interface: Desktop

Removes the specified custom attribute associated with the desktop.

Specified by:

removeAttribute in interface Desktop

getWebApp

public WebApp getWebApp()

Description copied from interface: Desktop

Returns the Web application this desktop belongs to.

Specified by:

getWebApp in interface Desktop

getRequestPath

public java.lang.String getRequestPath()

Description copied from interface: Desktop

Returns the path of the request that causes this desktop to be created, or "" if not available. In other words, it is the request path of the first page (see Page.getRequestPath()).

For example, "/userguide/index.zul" (a ZUML page is requested) or /test (a richlet).

Specified by:

getRequestPath in interface Desktop

See Also:

Page.getRequestPath()

getCurrentDirectory

public java.lang.String getCurrentDirectory()

Description copied from interface: Desktop

Returns the current directory (never null). It is empty if no current directory at all. Otherwise, it must end with '/'. In other words, you could use getCurrentDirectory() + relative_path.

Specified by:

getCurrentDirectory in interface Desktop

setCurrentDirectory

public void setCurrentDirectory(java.lang.String dir)

Description copied from interface: Desktop

Sets the current directory.

Specified by:

setCurrentDirectory in interface Desktop

Parameters:

dir - the current directory. If null, an empty string is assumed (means no current directory at all).

getRequestQueue

public RequestQueue getRequestQueue()

Description copied from interface: DesktopCtrl

Returns the request queue.

Specified by:

getRequestQueue in interface DesktopCtrl

setExecution

public void setExecution(Execution exec)

Description copied from interface: DesktopCtrl

Sets the execution (used to represent a lock). Called only internally (by UIEngine's implementation to activate an execution).

Specified by:

setExecution in interface DesktopCtrl

getNextKey

public int getNextKey()

Description copied from interface: DesktopCtrl

Returns the next available key which is unique in the whole desktop.

Specified by:

getNextKey in interface DesktopCtrl

getNextUuid

public java.lang.String getNextUuid()

Description copied from interface: DesktopCtrl

Returns the next available UUID for a component. The returned UUID is unique in the desktop. You can consider it as unique in the whole session, though it may not be true if RawId is used (developer's responsibility to avoid conflict), or integer overflow (too many UUID in one session, which can be considered as impossible).

Specified by:

getNextUuid in interface DesktopCtrl

addPage

public void addPage(Page page)

Description copied from interface: DesktopCtrl

Adds a page to this desktop. It must be called when a page is created.

This is one of the only few method you could access before activating an execution.

Specified by:

addPage in interface DesktopCtrl

removePage

public void removePage(Page page)

Description copied from interface: DesktopCtrl

Removes a page from this desktop.

NOTE: once a page is removed, you can NOT add it back. You shall just GC it.

Specified by:

removePage in interface DesktopCtrl

setBookmarkByClient

public void setBookmarkByClient(java.lang.String name)

Description copied from interface: DesktopCtrl

Sets the bookmark when receiving the onBookmarkChange command from the client.

Specified by:

setBookmarkByClient in interface DesktopCtrl

setId

public void setId(java.lang.String id)

Description copied from interface: DesktopCtrl

Sets the desktop identifier.

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

Specified by:

setId in interface DesktopCtrl

recoverDidFail

public void recoverDidFail(java.lang.Throwable ex)

Description copied from interface: DesktopCtrl

Called when the recoving failed.

Specified by:

recoverDidFail in interface DesktopCtrl

destroy

public void destroy()

Description copied from interface: DesktopCtrl

Called when the desktop is about to be destroyed.

Specified by:

destroy in interface DesktopCtrl

isAlive

public boolean isAlive()

Description copied from interface: Desktop

Returns whether the desktop is still alive. It returns false once it is destroyed.

Specified by:

isAlive in interface Desktop

See Also:

DesktopCtrl.destroy()

getSuspendedThreads

public java.util.Collection getSuspendedThreads()

Description copied from interface: DesktopCtrl

Returns a collection of suspended event processing threads, or empty if no suspended thread at all.

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 pathern 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();) {
      //...
    }
  }
}

Specified by:

getSuspendedThreads in interface DesktopCtrl

ceaseSuspendedThread

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

Description copied from interface: DesktopCtrl

Ceases the specified event thread.

Specified by:

ceaseSuspendedThread in interface DesktopCtrl

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.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

sessionWillPassivate

public void sessionWillPassivate(Session sess)

Description copied from interface: DesktopCtrl

Notification that the session, which owns this desktop, is about to be passivated (aka., serialized) by the Web container.

Specified by:

sessionWillPassivate in interface DesktopCtrl

sessionDidActivate

public void sessionDidActivate(Session sess)

Description copied from interface: DesktopCtrl

Notification that the session, which owns this desktop, has just been activated (aka., deserialized) by the Web container.

Specified by:

sessionDidActivate in interface DesktopCtrl

addListener

public void addListener(java.lang.Object listener)

Description copied from interface: Desktop

Adds a listener.

Note: if the listener is added twice, it will be invoked twice when a corresponding event occurs.

Specified by:

addListener in interface Desktop

Parameters:

listener - the listener. It cannot be null. It must be an instance that implements DesktopCleanup, ExecutionInit, ExecutionCleanup, UiLifeCycle, and/or EventInterceptor.
Note: EventThreadInit, EventThreadCleanup, EventThreadSuspend and EventThreadResume are not supported.

removeListener

public boolean removeListener(java.lang.Object listener)

Description copied from interface: Desktop

Removes a listener.

Specified by:

removeListener in interface Desktop

Returns:

whether the listener is removed successfully. Object.equals(java.lang.Object) is used to check whether a listener is added.

addEventInterceptor

public void addEventInterceptor(EventInterceptor ei)

Deprecated. As of release 3.0.6, replaced by addListener(java.lang.Object).

Specified by:

addEventInterceptor in interface Desktop

removeEventInterceptor

public boolean removeEventInterceptor(EventInterceptor ei)

Deprecated. As of release 3.0.6, replaced by removeListener(java.lang.Object).

Specified by:

removeEventInterceptor in interface Desktop

beforeSendEvent

public Event beforeSendEvent(Event event)

Description copied from interface: DesktopCtrl

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

Specified by:

beforeSendEvent in interface DesktopCtrl

beforePostEvent

public Event beforePostEvent(Event event)

Description copied from interface: DesktopCtrl

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

Specified by:

beforePostEvent in interface DesktopCtrl

beforeProcessEvent

public Event beforeProcessEvent(Event event)

Description copied from interface: DesktopCtrl

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

Specified by:

beforeProcessEvent in interface DesktopCtrl

afterProcessEvent

public void afterProcessEvent(Event event)

Description copied from interface: DesktopCtrl

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

Specified by:

afterProcessEvent in interface DesktopCtrl

invokeDesktopCleanups

public void invokeDesktopCleanups()

Description copied from interface: DesktopCtrl

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

Specified by:

invokeDesktopCleanups in interface DesktopCtrl

invokeExecutionInits

public void invokeExecutionInits(Execution exec,
                                 Execution parent)
                          throws UiException

Description copied from interface: DesktopCtrl

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

Specified by:

invokeExecutionInits in interface DesktopCtrl

Parameters:

exec - the execution that is created

parent - the previous execution, or null if no previous at all

Throws:

UiException - to prevent an execution from being created

invokeExecutionCleanups

public void invokeExecutionCleanups(Execution exec,
                                    Execution parent,
                                    java.util.List errs)

Description copied from interface: DesktopCtrl

Invokes ExecutionCleanup.cleanup(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Execution, java.util.List) 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.

Specified by:

invokeExecutionCleanups in interface DesktopCtrl

Parameters:

exec - the execution that is being destroyed

parent - the previous execution, or null if no previous at all

errs - a list of exceptions (java.lang.Throwable) if any exception occured before this method is called, or null if no exeption 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.

afterComponentAttached

public void afterComponentAttached(Component comp,
                                   Page page)

Description copied from interface: DesktopCtrl

Invokes UiLifeCycle.afterComponentAttached(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Page).

Specified by:

afterComponentAttached in interface DesktopCtrl

afterComponentDetached

public void afterComponentDetached(Component comp,
                                   Page prevpage)

Description copied from interface: DesktopCtrl

Invokes UiLifeCycle.afterComponentDetached(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Page).

Specified by:

afterComponentDetached in interface DesktopCtrl

afterComponentMoved

public void afterComponentMoved(Component parent,
                                Component child,
                                Component prevparent)

Description copied from interface: DesktopCtrl

Invokes UiLifeCycle.afterComponentMoved(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component).

Specified by:

afterComponentMoved in interface DesktopCtrl

prevparent - the previous parent. If it is the same as comp's Component.getParent(), comp is moved in the same parent.

enableServerPush

public boolean enableServerPush(boolean enable)

Description copied from interface: Desktop

Enables or disables the server-push feature. Before using any server-push threads, you have to enable it for the particular desktop first by use of this method. Refer to Executions.activate(org.zkoss.zk.ui.Desktop) for more details.

Default: false

This method uses the default class (defined by Device.getServerPushClass()) to instantiate the server-push controller.

Specified by:

enableServerPush in interface Desktop

Parameters:

enable - whether to enable or to disable the server-push feature.

See Also:

Executions.activate(org.zkoss.zk.ui.Desktop), Device.getServerPushClass()

enableServerPush

public boolean enableServerPush(ServerPush serverpush)

Description copied from interface: DesktopCtrl

Enables the server-push feature with the specified server-push controller.

Specified by:

enableServerPush in interface DesktopCtrl

Parameters:

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.

See Also:

Desktop.enableServerPush(boolean)

isServerPushEnabled

public boolean isServerPushEnabled()

Description copied from interface: Desktop

Returns whether the server-push feature is enabled for this desktop.

Default: false.

Specified by:

isServerPushEnabled in interface Desktop

getServerPush

public ServerPush getServerPush()

Description copied from interface: DesktopCtrl

Returns the server-push controller, or null if it is not enabled yet.

Specified by:

getServerPush in interface DesktopCtrl

activateServerPush

public boolean activateServerPush(long timeout)
                           throws java.lang.InterruptedException

Description copied from interface: DesktopCtrl

Activates the server push. It is called by Executions.activate(org.zkoss.zk.ui.Desktop).

Note: the server push must be enabled first (by use of Desktop.enableServerPush(boolean)).

Specified by:

activateServerPush in interface DesktopCtrl

Parameters:

timeout - the maximum time to wait in milliseconds. Ingored (i.e., never timeout) if non-positive.

Throws:

java.lang.InterruptedException

deactivateServerPush

public void deactivateServerPush()

Description copied from interface: DesktopCtrl

Deactivates the server push. It is called by Executions.deactivate(org.zkoss.zk.ui.Desktop).

Specified by:

deactivateServerPush in interface DesktopCtrl

setServerPushDelay

public void setServerPushDelay(int min,
                               int max,
                               int factor)

Description copied from interface: Desktop

Sets the delay between each polling. It can be called only the server push is enabled for this desktop (by use of Desktop.enableServerPush(boolean)).

Note: not all server-push controllers support this method. Currently, only on the client-polling-based controller (the default) supports this method.

To make the system more scalable, the implementation usually change the delay dynamically based on the loading. By specifying the minimal and maximal values, you can control the frequence to poll the server depending on the character of your Web applications.

Default: It looks up the value defined in the preferences (Configuration.getPreference(java.lang.String, java.lang.String)): PollingServerPush.delay.min PollingServerPush.delay.max, and PollingServerPush.delay.factor. If not defined, min is 1100, max is 10000 and factor is 5.

Specified by:

setServerPushDelay in interface Desktop

Parameters:

min - the minimal delay to poll the server for any pending server-push threads. Ignore (aka., the default value is used) if non-positive. Unit: milliseconds.

max - the maximal delay to poll the server for any pending server-push threads. Ignore (aka., the default value is used) if non-positive. Unit: milliseconds.

factor - the delay factor. The real delay is the processing time multiplies the delay factor. For example, if the last request took 1 second to process, then the client polling will be delayed for 1 x factor seconds, unless it is value Ignore (aka., the default value is used) if non-positive.

onPiggybackListened

public void onPiggybackListened(Component comp,
                                boolean listen)

Description copied from interface: DesktopCtrl

Called when a component added or removed a listener for Events.ON_PIGGYBACK.

The implementation usualy uses it to optimize whether to call the listener when DesktopCtrl.onPiggyback() is called.

Specified by:

onPiggybackListened in interface DesktopCtrl

Parameters:

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

onPiggyback

public void onPiggyback()

Description copied from interface: DesktopCtrl

Called each time ZK Update Engine processes all events. It is used to implement the piggyback feature (see Events.ON_PIGGYBACK).

Used only internally. Application develepers shall not call it.

Specified by:

onPiggyback in interface DesktopCtrl

responseSent

public void responseSent(java.lang.String channel,
                         java.lang.String reqId,
                         java.lang.Object response)

Description copied from interface: DesktopCtrl

Called when ZK Update Engine has sent a response to the client.

Note: the implementation has to maintain one last-sent response information for each channel, since a different channel has different set of request IDs and might resend in a different condition.

Specified by:

responseSent in interface DesktopCtrl

Parameters:

channel - the request channel. For example, "au" for AU requests and "cm" for Comet requests.

reqId - the request ID that the response is generated for. Ingore if null.

response - the response infomation. Ignored if reqId is null. The real value depends on the caller.

getLastResponse

public java.lang.Object getLastResponse(java.lang.String channel,
                                        java.lang.String reqId)

Description copied from interface: DesktopCtrl

Returns the information of response for the last request, or null if no response yet, or the specified request ID doesn't match the last one (passed to DesktopCtrl.responseSent(java.lang.String, java.lang.String, java.lang.Object)).

The return value is the value passed to resInfo when calling DesktopCtrl.responseSent(java.lang.String, java.lang.String, java.lang.Object). The real value depends on the caller.

Specified by:

getLastResponse in interface DesktopCtrl

getResponseId

public int getResponseId(boolean advance)

Description copied from interface: DesktopCtrl

Returns the sequence ID of the response. The client and server uses the sequence ID to make sure the responses are processed in the correct order.

The range of the sequence IDs is 1~999.

Specified by:

getResponseId in interface DesktopCtrl

Parameters:

advance - whether to advance the number before returning. If true, the ID is increased and then returned. If false, the previous value is returned

setResponseId

public void setResponseId(int resId)

Description copied from interface: DesktopCtrl

Sets the sequence ID of the response.

It is rarely called other than in the recovering mode, i.e., ExecutionCtrl.isRecovering() is true.

Specified by:

setResponseId in interface DesktopCtrl

Parameters:

resId - a value between 1 and 999. You can reset the ID by passing a non-positive value.

invalidate

public void invalidate()

Description copied from interface: Desktop

Invalidates the desktop. All pages will be redrawn.

Specified by:

invalidate in interface Desktop