Package org.zkoss.zk.ui.impl

## Class DesktopImpl

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

- All Implemented Interfaces:
    `java.io.Serializable`, `Desktop`, `Scope`, `DesktopCtrl`

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

  The implementation of `Desktop`.

  Note: though `DesktopImpl` is serializable, it is designed to work with Web container to enable the serialization of sessions. It is not suggested to serialize and 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, java.lang.String updateURI, java.lang.String path, java.lang.String deviceType, java.lang.Object request)` |
    `DesktopImpl​(WebApp wapp, java.lang.String updateURI, java.lang.String resourceURI, java.lang.String path, java.lang.String deviceType, java.lang.Object request)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    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​(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​(boolean enable, java.io.Serializable enabler)` | Enable/Disable serverpush using reference counting, so that multiple enablers can use the same serverpush and deregister whenever they want.
    `boolean` | `enableServerPush​(ServerPush serverpush)` | Enables the server-push feature with the specified server-push controller.
    `java.lang.Object` | `getActivationLock()` | Returns the lock used to activate an execution.
    `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.
    `java.lang.String` | `getResourceURI​(java.lang.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.
    `Session` | `getSession()` | Returns the session of this desktop.
    `Storage` | `getStorage()` | Returns the storage in a desktop scope.
    `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<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​(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` | `pushHistoryState​(java.lang.Object state, java.lang.String title, java.lang.String url)` | Pushes a new history state.
    `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)` | 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` | `replaceHistoryState​(java.lang.Object state, java.lang.String title, java.lang.String url)` | Replaces the current history state.
    `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:
        `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,
                             java.lang.String updateURI,
                             java.lang.String resourceURI,
                             java.lang.String path,
                             java.lang.String deviceType,
                             java.lang.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 Detail

    - #### 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`

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

    - #### getResourceURI

          public java.lang.String getResourceURI​(java.lang.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 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)

      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​(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)`, 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`

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

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

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

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

    - #### 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.
         - 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 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<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,
                                          java.io.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 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>, 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`

    - #### 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​(java.lang.Object state,
                                       java.lang.String title,
                                       java.lang.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​(java.lang.Object state,
                                          java.lang.String title,
                                          java.lang.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.