Package org.zkoss.zk.ui.impl

Class DesktopImpl

java.lang.Object

org.zkoss.zk.ui.impl.DesktopImpl

All Implemented Interfaces:

Serializable, Desktop, Scope, DesktopCtrl

public class DesktopImpl
extends Object
implements Desktop, DesktopCtrl, 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 deserialize 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

Constructors

Constructor	Description
DesktopImpl(WebApp wapp, String updateURI, String path, String deviceType, Object request)
DesktopImpl(WebApp wapp, String updateURI, String resourceURI, String path, String deviceType, Object request)

Method Summary

Modifier and Type	Method	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	addListener(Object listener)	Adds a listener.
void	addPage(Page page)	Adds a page to this desktop.
boolean	addScopeListener(ScopeListener listener)	Adds a listener to listen whether this scope is changed.
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, String cause)	Ceases the specified event thread.
void	deactivateServerPush()	Deactivates the thread that has invoked DesktopCtrl.activateServerPush(long) successfully.
void	destroy()	Called when the desktop is about to be destroyed.
boolean	enableServerPush(boolean enable)	Enables or disables the server-push feature.
boolean	enableServerPush(boolean enable, 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.
Object	getActivationLock()	Returns the lock used to activate an execution.
Object	getAttribute(String name)	Returns the value of the specified custom attribute associated with the desktop.
Object	getAttribute(String name, boolean recurse)	Returns the custom attribute associated with this object.
Map<String,Object>	getAttributes()	Returns all custom attributes associated with this desktop.
String	getBookmark()	Returns the current bookmark (never null).
Component	getComponentByUuid(String uuid)	Returns the component of the specified UUID (Component.getUuid()).
Component	getComponentByUuidIfAny(String uuid)	Returns the component of the specified UUID (Component.getUuid()), or null if not found.
Collection<Component>	getComponents()	Returns all components contained in this desktop.
String	getCurrentDirectory()	Returns the current directory (never null).
Device	getDevice()	Returns the device that is associated with this desktop.
String	getDeviceType()	Returns the device type that this desktop belongs to.
org.zkoss.util.media.Media	getDownloadMedia(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.
String	getDownloadMediaURI(org.zkoss.util.media.Media media, String pathInfo)	Returns URI for a media that is used to download to the client.
String	getDynamicMediaURI(Component comp, 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 serving any execution (a.k.a., not locked).
Page	getFirstPage()	Returns the first page, or null if no page at all (happens when the desktop has been destroyed)
String	getId()	Returns ID of this desktop.
Object	getLastResponse(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 DesktopCtrl.responseSent(java.lang.String, java.lang.Object)).
int	getNextKey()	Returns the next available key which is unique in the whole desktop.
String	getNextUuid(Component comp)	Returns the next available UUID for a component.
String	getNextUuid(Page page)	Returns the next available UUID for a page.
Page	getPage(String pageId)	Returns the page of the specified ID or UUID.
Page	getPageIfAny(String pageId)	Returns the page of the specified ID or UUID, or null if no such page.
Collection<Page>	getPages()	Returns a readonly collection of all Page in this desktop.
String	getQueryString()	Returns the query string that is contained in the request URL after the path (Desktop.getRequestPath()), or null if the URL does not have a query string.
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.
String	getResourceURI(String pathInfo)	Returns the URI for ZK resource.
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.
final Session	getSession()	Returns the session of this desktop.
Storage	getStorage()	Returns the storage in a desktop scope.
Collection<EventProcessingThread>	getSuspendedThreads()	Returns a collection of suspended event processing threads, or empty if no suspended thread at all.
String	getUpdateURI(String pathInfo)	Returns the URI for asynchronous update.
Visualizer	getVisualizer()	Returns the visualizer associated with this desktop.
WebApp	getWebApp()	Returns the Web application this desktop belongs to.
boolean	hasAttribute(String name)	Returns if a custom attribute is associated with this object (scope).
boolean	hasAttribute(String name, boolean recurse)	Returns if a custom attribute is associated with this object.
boolean	hasPage(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, List<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).
boolean	isAlive()	Returns whether the desktop is still alive.
boolean	isServerPushEnabled()	Returns whether the server-push feature is enabled for this desktop.
Component	mapComponent(String uuid, Component comp)	Maps a component associated with the given UUID to this page.
protected RequestQueue	newRequestQueue()	Creates the request queue.
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.
List<AuResponse>	piggyResponse(Collection<AuResponse> response, boolean reset)	Adds the responses to the so-called piggy-back queue.
void	pushHistoryState(Object state, String title, String url)	Pushes a new history state.
void	recoverDidFail(Throwable ex)	Called when the recovering failed.
void	recycle()	Called when the desktop has been recycled.
Object	removeAttribute(String name)	Removes the specified custom attribute associated with the desktop.
Object	removeAttribute(String name, boolean recurse)	Removes the custom attribute associated with this scope.
boolean	removeComponent(Component comp)	Removes a component to this page.
boolean	removeListener(Object listener)	Removes a listener.
void	removePage(Page page)	Removes a page from this desktop.
boolean	removeScopeListener(ScopeListener listener)	Removes a change listener from this scope.
void	replaceHistoryState(Object state, String title, String url)	Replaces the current history state.
void	responseSent(String reqId, Object response)	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> void	scheduleServerPush(EventListener<T> listener, 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.
Object	setAttribute(String name, Object value)	Sets the value of the specified custom attribute associated with the desktop.
Object	setAttribute(String name, Object value, boolean recurse)	Sets the custom attribute associated with this scope, or the parent scope.
void	setBookmark(String name)	Sets a bookmark to this desktop.
void	setBookmark(String name, boolean replace)	Sets the bookmark to this desktop. with more control.
void	setCurrentDirectory(String dir)	Sets the current directory.
void	setDeviceType(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(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.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Details

DesktopImpl

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

Parameters:

wapp - the web application

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.

request - the request (HttpServletRequest if HTTP)

Since:

3.0.1

DesktopImpl

public DesktopImpl(WebApp wapp,
 String updateURI,
 String resourceURI,
 String path,
 String deviceType,
 Object request)

Parameters:

wapp - the web application

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

resourceURI - the URI to access the resource 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.

request - the request (HttpServletRequest if HTTP)

Since:

9.5.0

Method Details

getQueryString

public String getQueryString()

Description copied from interface: Desktop

Returns the query string that is contained in the request URL after the path (Desktop.getRequestPath()), or null if the URL does not have a query string.

Specified by:

getQueryString in interface Desktop

getId

public 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 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(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 serving any execution (a.k.a., 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 String getUpdateURI(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

getResourceURI

public String getResourceURI(String pathInfo)

Description copied from interface: Desktop

Returns the URI for ZK resource.

Specified by:

getResourceURI in interface Desktop

Parameters:

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

getDynamicMediaURI

public String getDynamicMediaURI(Component comp,
 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 String getDownloadMediaURI(org.zkoss.util.media.Media media,
 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 org.zkoss.util.media.Media getDownloadMedia(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(String pageId)

Description copied from interface: Desktop

Returns the page of the specified ID or UUID.

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

Specified by:

getPage in interface Desktop

Parameters:

pageId - the page's ID or UUID. ID has the higher priority.

getPageIfAny

public Page getPageIfAny(String pageId)

Description copied from interface: Desktop

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

Specified by:

getPageIfAny in interface Desktop

Parameters:

pageId - the page's ID or UUID. ID has the higher priority.

hasPage

public boolean hasPage(String pageId)

Description copied from interface: Desktop

Returns whether a page exists.

Specified by:

hasPage in interface Desktop

getPages

public Collection<Page> getPages()

Description copied from interface: Desktop

Returns a readonly collection of all Page in this desktop.

Specified by:

getPages in interface Desktop

getFirstPage

public Page getFirstPage()

Description copied from interface: Desktop

Returns the first page, or null if no page at all (happens when the desktop has been destroyed)

Specified by:

getFirstPage in interface Desktop

getBookmark

public 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(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.

It is the same as setBookmark(name, false)

Specified by:

setBookmark in interface Desktop

setBookmark

public void setBookmark(String name,
 boolean replace)

Description copied from interface: Desktop

Sets the bookmark to this desktop. with more control.

Specified by:

setBookmark in interface Desktop

Parameters:

name - the name of the bookmark

replace - if true, the bookmark is replaced (in the history list)

See Also:

• Desktop.setBookmark(String)

getComponents

public Collection<Component> getComponents()

Description copied from interface: Desktop

Returns all components contained in this desktop.

Specified by:

getComponents in interface Desktop

getComponentByUuid

public Component getComponentByUuid(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(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 boolean removeComponent(Component comp)

Description copied from interface: DesktopCtrl

Removes a component to this page.

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

Specified by:

removeComponent in interface DesktopCtrl

Returns:

false always since 10.0.0 (Deprecated: whether UUID is recycled. If true, the caller shall reset UUID of the give component.)

mapComponent

public Component mapComponent(String uuid,
 Component comp)

Description copied from interface: DesktopCtrl

Maps a component associated with the given UUID to this page. Notice that the given uuid can be different from comp's UUID (Component.getUuid()).

If the given component is null, the mapping of UUID is removed.

Unlike DesktopCtrl.addComponent(org.zkoss.zk.ui.Component) and DesktopCtrl.removeComponent(org.zkoss.zk.ui.Component), 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.

Specified by:

mapComponent in interface DesktopCtrl

comp - the component to associate with the given UUID. If not, the association (i.e., mapping) is removed.

Returns:

the previous component that was associated with the given UUID.

getAttributes

public Map<String,Object> 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 Object getAttribute(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

getAttribute

public Object getAttribute(String name,
 boolean recurse)

Description copied from interface: Scope

Returns the custom attribute associated with this object.

Specified by:

getAttribute in interface Scope

recurse - whether to search its ancestor scope. If true and the current scope doen't define the attribute, it searches up its ancestor to see any of them has defined the specified attribute.

hasAttribute

public boolean hasAttribute(String name)

Description copied from interface: Scope

Returns if a custom attribute is associated with this object (scope).

Notice that null is a valid value, so you can tell if an attribute is associated by examining the return value of Scope.getAttribute(java.lang.String).

Specified by:

hasAttribute in interface Scope

hasAttribute

public boolean hasAttribute(String name,
 boolean recurse)

Description copied from interface: Scope

Returns if a custom attribute is associated with this object.

Notice that null is a valid value, so you can tell if an attribute is associated by examining the return value of Scope.getAttribute(java.lang.String).

Specified by:

hasAttribute in interface Scope

recurse - whether to search its ancestor scope. If true and the current scope doen't define the attribute, it searches up its ancestor to see any of them has defined the specified attribute.

setAttribute

public Object setAttribute(String name,
 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

Specified by:

setAttribute in interface Scope

Returns:

the previous value associated with the attribute, if any

setAttribute

public Object setAttribute(String name,
 Object value,
 boolean recurse)

Description copied from interface: Scope

Sets the custom attribute associated with this scope, or the parent scope.

Specified by:

setAttribute in interface Scope

recurse - whether to look up the parent scope for the existence of the attribute.
If recurse is true and the attribute is defined in one of its ancestor (including page), the attribute is replaced. Otherwise, it is the same as Scope.setAttribute(String,Object).

removeAttribute

public Object removeAttribute(String name)

Description copied from interface: Desktop

Removes the specified custom attribute associated with the desktop.

Specified by:

removeAttribute in interface Desktop

Specified by:

removeAttribute in interface Scope

Returns:

the previous value associated with the attribute, if any,

removeAttribute

public Object removeAttribute(String name,
 boolean recurse)

Description copied from interface: Scope

Removes the custom attribute associated with this scope.

Specified by:

removeAttribute in interface Scope

recurse - whether to look up the parent scope for the existence of the attribute.
If recurse is true and the attribute is defined in one of its ancestor (including page), the attribute is removed. Otherwise, it is the same as Scope.removeAttribute(String).

addScopeListener

public boolean addScopeListener(ScopeListener listener)

Description copied from interface: Scope

Adds a listener to listen whether this scope is changed. The listener is called when a custom attribute is added, removed, or the parent is changed.

Specified by:

addScopeListener in interface Scope

Returns:

weather the listener is added successfully. Note: if the resolver was added before, it won't be added again and this method returns false.

removeScopeListener

public boolean removeScopeListener(ScopeListener listener)

Description copied from interface: Scope

Removes a change listener from this scope.

Specified by:

removeScopeListener in interface Scope

Returns:

false if listener is not added before.

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 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, "/foo/index.zul" (a ZUML page is requested) or /test (a richlet).

Specified by:

getRequestPath in interface Desktop

See Also:

• Page.getRequestPath()

getCurrentDirectory

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

Used only to implement UiEngine.

Specified by:

setExecution in interface DesktopCtrl

service

public void service(AuRequest request,
 boolean everError)

Description copied from interface: DesktopCtrl

Processes an AU request. Notice that not only the requests for a desktop but also the requests for any component in the desktop will go thru this method.

To override the default processing, register an AU request service AuService by invoking Desktop.addListener(java.lang.Object).

1. This method first invokes the registered AU request service (AuService) one-by-one, until the first one returns true.
2. If none of them returns true or no AU service at all, it checks if the request is targeting a component (i.e., AuRequest.getComponent() is not null).
3. If it is targeting a component, it invokes ComponentCtrl.service(org.zkoss.zk.au.AuRequest, boolean) to handle the service.
4. If it is not targeting a component (i.e., targeting to this desktop), it handles as follows.
   • It handles the recognized requests, including onBookmarkChange, onURIChange and onClientInfo.
   • If the request is not one of above, it converts the request to an event (by 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 DesktopCtrl.afterProcessEvent(org.zkoss.zk.ui.event.Event).

Specified by:

service in interface DesktopCtrl

everError - if any error ever occurred before processing this request. In other words, indicates if the previous request causes any exception.

getVisualizer

public Visualizer getVisualizer()

Description copied from interface: DesktopCtrl

Returns the visualizer associated with this desktop.

Used only to implement UiEngine.

Specified by:

getVisualizer in interface DesktopCtrl

setVisualizer

public void setVisualizer(Visualizer uv)

Description copied from interface: DesktopCtrl

Sets the visualizer associated with is desktop.

Used only to implement UiEngine.

Specified by:

setVisualizer in interface DesktopCtrl

getActivationLock

public Object getActivationLock()

Description copied from interface: DesktopCtrl

Returns the lock used to activate an execution. Before calling DesktopCtrl.setVisualizer(org.zkoss.zk.ui.sys.Visualizer), this object returned by this method must be locked first.

Used only to implement UiEngine.

Specified by:

getActivationLock 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 String getNextUuid(Page page)

Description copied from interface: DesktopCtrl

Returns the next available UUID for a page. 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), integer overflow (too many UUID in one session, which can be considered as impossible), or a custom ID generator (IdGenerator) is used.

Specified by:

getNextUuid in interface DesktopCtrl

getNextUuid

public String getNextUuid(Component comp)

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), integer overflow (too many UUID in one session, which can be considered as impossible), or a custom ID generator (IdGenerator) is used.

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

setId

public void setId(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(Throwable ex)

Description copied from interface: DesktopCtrl

Called when the recovering failed.

Specified by:

recoverDidFail in interface DesktopCtrl

recycle

public void recycle()

Description copied from interface: DesktopCtrl

Called when the desktop has been recycled. More precisely, it is called when the desktop is no longer used and ready to be re-used later.

Specified by:

recycle 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()

destroy

public void destroy()

Description copied from interface: DesktopCtrl

Called when the desktop is about to be destroyed.

Specified by:

destroy in interface DesktopCtrl

getSuspendedThreads

public Collection<EventProcessingThread> 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 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();) {
          //...
        }
        }
        }

Specified by:

getSuspendedThreads in interface DesktopCtrl

ceaseSuspendedThread

public boolean ceaseSuspendedThread(EventProcessingThread evtthd,
 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 String toString()

Overrides:

toString in class 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 (a.k.a., 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 (a.k.a., deserialized) by the Web container.

Specified by:

sessionDidActivate in interface DesktopCtrl

addListener

public void addListener(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, EventInterceptor and/or AuService.
Note: DesktopInit, EventThreadInit, EventThreadCleanup, EventThreadSuspend and EventThreadResume are not supported.

removeListener

public boolean removeListener(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.

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)
                         throws Exception

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

Throws:

Exception

afterProcessEvent

public void afterProcessEvent(Event event)
                       throws Exception

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

Throws:

Exception

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,
 List<Throwable> errs)

Description copied from interface: DesktopCtrl

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

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

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()
• DesktopCtrl.enableServerPush(org.zkoss.zk.ui.sys.ServerPush)

enableServerPush

public boolean enableServerPush(boolean enable,
 Serializable enabler)

Description copied from interface: DesktopCtrl

Enable/Disable serverpush using reference counting, so that multiple enablers can use the same serverpush and deregister whenever they want.

Specified by:

enableServerPush in interface DesktopCtrl

Parameters:

enable - true/false enable/disable serverpush

enabler - the same reference must be used to disable again

Returns:

Currently only used by DesktopEventQueue to enable several eventqueues to use the same ServerPush

enableServerPush

public boolean enableServerPush(ServerPush serverpush)

Description copied from interface: DesktopCtrl

Enables the server-push feature with the specified server-push controller. If you want to use the default serverpush, use 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.

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

scheduleServerPush

public <T extends Event> void scheduleServerPush(EventListener<T> listener,
 T event)

Description copied from interface: DesktopCtrl

Schedules a task to run under the server push of the given desktop asynchronously. It is called by Executions.schedule(org.zkoss.zk.ui.Desktop, org.zkoss.zk.ui.event.EventListener<T>, T). Don't call it directly.

Like DesktopCtrl.activateServerPush(long) and DesktopCtrl.deactivateServerPush(), this method could be called in any thread, so the implementation of this method has to be safe for concurrent access.

Specified by:

scheduleServerPush in interface DesktopCtrl

Parameters:

listener - the task to execute

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

scheduledServerPush

public boolean scheduledServerPush()

Description copied from interface: DesktopCtrl

Returns if there is any scheduled task for server push.

Specified by:

scheduledServerPush in interface DesktopCtrl

activateServerPush

public boolean activateServerPush(long timeout)
                           throws InterruptedException

Description copied from interface: DesktopCtrl

Activates the current thread for accessing this desktop by the server push. It is called by Executions.activate(org.zkoss.zk.ui.Desktop). Don't call it directly.

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

Specified by:

activateServerPush in interface DesktopCtrl

Parameters:

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

Throws:

InterruptedException

deactivateServerPush

public void deactivateServerPush()

Description copied from interface: DesktopCtrl

Deactivates the thread that has invoked DesktopCtrl.activateServerPush(long) successfully. It is called by Executions.deactivate(org.zkoss.zk.ui.Desktop). Don't call it directly.

Specified by:

deactivateServerPush in interface DesktopCtrl

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 usually 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 when ZK Update Engine retrieves events. It is used to implement the piggyback feature by posting the events (see 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.

Specified by:

onPiggyback in interface DesktopCtrl

responseSent

public void responseSent(String reqId,
 Object response)

Description copied from interface: DesktopCtrl

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

Specified by:

responseSent in interface DesktopCtrl

Parameters:

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

response - the response. Ignored if reqId is null.

getLastResponse

public Object getLastResponse(String reqId)

Description copied from interface: DesktopCtrl

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 DesktopCtrl.responseSent(java.lang.String, java.lang.Object)).

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

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.

piggyResponse

public List<AuResponse> piggyResponse(Collection<AuResponse> response,
 boolean reset)

Description copied from interface: DesktopCtrl

Adds the responses to the so-called piggy-back queue. The responses in the piggy-back queue will be sent in the next AU request.

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.

Specified by:

piggyResponse in interface DesktopCtrl

Parameters:

response - the responses to be appended to the piggy-back queue.

reset - whether to reset the piggy-back queue after returning the queued responses.

Returns:

all responses in the piggy-back queue, or null if nothing in the queue.

invalidate

public void invalidate()

Description copied from interface: Desktop

Invalidates the desktop. All pages will be redrawn.

Specified by:

invalidate in interface Desktop

getStorage

public Storage getStorage()

Description copied from interface: Desktop

Returns the storage in a desktop scope.

Specified by:

getStorage in interface Desktop

Returns:

a storage implementation, never null.

pushHistoryState

public void pushHistoryState(Object state,
 String title,
 String url)

Description copied from interface: Desktop

Pushes a new history state.

Specified by:

pushHistoryState in interface Desktop

Parameters:

state - a state object.

title - a title for the state. May be ignored by some browsers.

url - the history entry's URL. Could be null.

replaceHistoryState

public void replaceHistoryState(Object state,
 String title,
 String url)

Description copied from interface: Desktop

Replaces the current history state.

Specified by:

replaceHistoryState in interface Desktop

Parameters:

state - a state object.

title - a title for the state. May be ignored by some browsers.

url - the history entry's URL. Could be null.