org.zkoss.zk.ui
Interface Desktop

All Known Implementing Classes:

DesktopImpl

public interface Desktop

Represents a desktop. All pages that is created from the same URL is called a desktop.

A desktop is created automatically when the first page is created during a request.

To access a Page, its desktop must be locked first. Once a desktop is locked to a request, all pages contained in this desktop are free to access.

Author:

tomyeh

Method Summary

void	addEventInterceptor(EventInterceptor ei) Adds an event interceptor to this desktop.
boolean	enableServerPush(boolean enable) Enables or disables the server-push feature.
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.
java.lang.String	getDownloadMediaURI(org.zkoss.util.media.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.
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.
Session	getSession() Returns the session of this desktop.
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 id) Returns whether a page exists.
boolean	isAlive() Returns whether the desktop is still alive.
boolean	isServerPushEnabled() Returns whether the server-push feature is enabled for this desktop.
java.lang.Object	removeAttribute(java.lang.String name) Removes the specified custom attribute associated with the desktop.
boolean	removeEventInterceptor(EventInterceptor ei) Removes an event interceptor from this desktop.
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	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	setServerPushDelay(int min, int max, int factor) Sets the delay between each polling.

Method Detail

getDeviceType

java.lang.String getDeviceType()

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.

setDeviceType

void setDeviceType(java.lang.String deviceType)

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 (getDevice()) will be dropped and recreated at the next invocation to getDevice().

Throws:

UiException - if any component is attached to a page of the desktop.

getDevice

Device getDevice()

Returns the device that is associated with this desktop.

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

isAlive

boolean isAlive()

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

See Also:

DesktopCtrl.destroy()

getId

java.lang.String getId()

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

getExecution

Execution getExecution()

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

getSession

Session getSession()

Returns the session of this desktop.

getWebApp

WebApp getWebApp()

Returns the Web application this desktop belongs to.

getPage

Page getPage(java.lang.String pageId)
             throws ComponentNotFoundException

Returns the page of the specified ID.

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

Throws:

ComponentNotFoundException - if page not found

getPageIfAny

Page getPageIfAny(java.lang.String pageId)

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

Since:

2.4.1

getPages

java.util.Collection getPages()

Returns a readonly collection of all Page in this desktop.

hasPage

boolean hasPage(java.lang.String id)

Returns whether a page exists.

getAttributes

java.util.Map getAttributes()

Returns all custom attributes associated with this desktop.

getAttribute

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

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

setAttribute

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

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

removeAttribute

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

Removes the specified custom attribute associated with the desktop.

getComponents

java.util.Collection getComponents()

Returns all components contained in this desktop.

getComponentByUuid

Component getComponentByUuid(java.lang.String uuid)

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

Throws:

ComponentNotFoundException - if component not found

getComponentByUuidIfAny

Component getComponentByUuidIfAny(java.lang.String uuid)

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

getUpdateURI

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

Returns the URI for asynchronous update.

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

Parameters:

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

getRequestPath

java.lang.String getRequestPath()

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

Since:

3.0.0

See Also:

Page.getRequestPath()

getCurrentDirectory

java.lang.String getCurrentDirectory()

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.

setCurrentDirectory

void setCurrentDirectory(java.lang.String dir)

Sets the current directory.

Parameters:

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

getBookmark

java.lang.String getBookmark()

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

setBookmark

void setBookmark(java.lang.String name)

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

getDynamicMediaURI

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

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.

getDownloadMediaURI

java.lang.String getDownloadMediaURI(org.zkoss.util.media.Media media,
                                     java.lang.String pathInfo)

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.

enableServerPush

boolean enableServerPush(boolean enable)

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.

Parameters:

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

Since:

3.0.0

See Also:

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

setServerPushDelay

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

Sets the delay between each polling. It can be called only the server push is enabled for this desktop (by use of 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.

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.

Since:

3.0.0

isServerPushEnabled

boolean isServerPushEnabled()

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

Default: false.

Since:

3.0.0

addEventInterceptor

void addEventInterceptor(EventInterceptor ei)

Adds an event interceptor to this desktop.

Since:

3.0.0

removeEventInterceptor

boolean removeEventInterceptor(EventInterceptor ei)

Removes an event interceptor from this desktop.

Returns:

whether the interceptor is removed successfully.

Since:

3.0.0