org.zkoss.zk.ui.impl
Class DesktopImpl

java.lang.Object
  extended by 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 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
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 current thread for accessing this desktop by the server push.
 void addComponent(Component comp)
          Adds a component to this page.
 void addListener(java.lang.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, java.lang.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(ServerPush serverpush)
          Enables the server-push feature with the specified server-push controller.
 java.lang.Object getActivationLock()
          Returns the lock used to activate an execution.
 java.lang.Object getAttribute(java.lang.String name)
          Returns the value of the specified custom attribute associated with the desktop.
 java.lang.Object getAttribute(java.lang.String name, boolean recurse)
          Returns the custom attribute associated with this object.
 java.util.Map<java.lang.String,java.lang.Object> 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<Component> 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 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)
 java.lang.String getId()
          Returns ID of this desktop.
 java.lang.Object getLastResponse(java.lang.String reqId)
          Returns the response for the last request, or null if no response yet, or the specified request ID doesn't match the last one (passed to DesktopCtrl.responseSent(java.lang.String, java.lang.Object)).
 int getNextKey()
          Returns the next available key which is unique in the whole desktop.
 java.lang.String getNextUuid(Component comp)
          Returns the next available UUID for a component.
 java.lang.String getNextUuid(Page page)
          Returns the next available UUID for a page.
 Page getPage(java.lang.String pageId)
          Returns the page of the specified ID or UUID.
 Page getPageIfAny(java.lang.String pageId)
          Returns the page of the specified ID or UUID, or null if no such page.
 java.util.Collection<Page> getPages()
          Returns a readonly collection of all Page in this desktop.
 java.lang.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.
 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<EventProcessingThread> 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.
 Visualizer getVisualizer()
          Returns the visualizer associated with this desktop.
 WebApp getWebApp()
          Returns the Web application this desktop belongs to.
 boolean hasAttribute(java.lang.String name)
          Returns if a custom attribute is associated with this object (scope).
 boolean hasAttribute(java.lang.String name, boolean recurse)
          Returns if a custom attribute is associated with this object.
 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<java.lang.Throwable> 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.
 Component mapComponent(java.lang.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.
 java.util.List<AuResponse> piggyResponse(java.util.Collection<AuResponse> response, boolean reset)
          Adds the responses to the so-called piggy-back queue.
 void recoverDidFail(java.lang.Throwable ex)
          Called when the recovering failed.
 void recycle()
          Called when the desktop has been recycled.
 java.lang.Object removeAttribute(java.lang.String name)
          Removes the specified custom attribute associated with the desktop.
 java.lang.Object removeAttribute(java.lang.String name, boolean recurse)
          Removes the custom attribute associated with this scope.
 boolean removeComponent(Component comp, boolean recycleAllowed)
          Removes a component to this page.
 boolean removeListener(java.lang.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 responseSent(java.lang.String reqId, java.lang.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.
 java.lang.Object setAttribute(java.lang.String name, java.lang.Object value)
          Sets the value of the specified custom attribute associated with the desktop.
 java.lang.Object setAttribute(java.lang.String name, java.lang.Object value, boolean recurse)
          Sets the custom attribute associated with this scope, or the parent scope.
 void setBookmark(java.lang.String name)
          Sets a bookmark to this desktop.
 void setBookmark(java.lang.String name, boolean replace)
          Sets the bookmark to this desktop. with more control.
 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 setVisualizer(Visualizer uv)
          Sets the visualizer associated with is desktop.
 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 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 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 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(java.lang.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(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<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 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.

It is the same as setBookmark(name, false)

Specified by:
setBookmark in interface Desktop

setBookmark

public void setBookmark(java.lang.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 java.util.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(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 boolean removeComponent(Component comp,
                               boolean recycleAllowed)
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
recycleAllowed - whether it is OK to recycle UUID.
Returns:
whether UUID is recycled. If true, the caller shall reset UUID of the give component.

mapComponent

public Component mapComponent(java.lang.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, boolean), this method simply replaces the mapping if the given UUID is already mapped to the other component.

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

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 java.util.Map<java.lang.String,java.lang.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 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

hasAttribute

public boolean hasAttribute(java.lang.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

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
Specified by:
setAttribute in interface Scope
Returns:
the previous value associated with the attribute, if any

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
Specified by:
removeAttribute in interface Scope
Returns:
the previous value associated with the attribute, if any,

getAttribute

public java.lang.Object getAttribute(java.lang.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(java.lang.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 java.lang.Object setAttribute(java.lang.String name,
                                     java.lang.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 java.lang.Object removeAttribute(java.lang.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 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, "/foo/index.zul" (a ZUML page is requested) or /test (a richlet).

Specified by:
getRequestPath in interface Desktop
See Also:
Page.getRequestPath()

getQueryString

public java.lang.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

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

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.

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 java.lang.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 java.lang.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 java.lang.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(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 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 java.util.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,
                                    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 (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(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, EventInterceptor and/or AuService.
Note: DesktopInit, 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.

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 java.lang.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:
java.lang.Exception

afterProcessEvent

public void afterProcessEvent(Event event)
                       throws java.lang.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:
java.lang.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,
                                    java.util.List<java.lang.Throwable> 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 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(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). 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 java.lang.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), 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:
java.lang.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(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.

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 java.lang.Object getLastResponse(java.lang.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 java.util.List<AuResponse> piggyResponse(java.util.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


Copyright © 2005-2011 Potix Corporation. All Rights Reserved. SourceForge.net Logo