Package org.zkoss.zk.ui.util

## Interface DesktopRecycle

- All Known Implementing Classes:
    `DesktopRecycle`

      public interface DesktopRecycle

  Used to recycle the desktop (`Desktop`). By recycling the desktop, we mean to re-use the same desktop for the same URI if applicable. For example, if an user navigates to other URL and navigates back, the application can re-use the same desktop (by implementing this interface). It is useful if the page takes a lot of time to prepare.

  A typical implementation (such as `DesktopRecycle`) caches the desktop when `beforeRemove(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Desktop, int)` is called, and then return it if `beforeService(org.zkoss.zk.ui.Execution, java.lang.String)` matches it.

  Please refer to Performance Tips for more information.

  Since:
    5.0.0
  Author:
    tomyeh

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `afterRemove​(Session sess, Desktop desktop)` | Called after a desktop is removed.
    `void` | `afterService​(Desktop desktop)` | Called after the request is served.
    `boolean` | `beforeRemove​(Execution exec, Desktop desktop, int cause)` | Called when the client asks the server to remove a desktop because of the user's navigating to other URL or refreshing the page.
    `Desktop` | `beforeService​(Execution exec, java.lang.String uri)` | Called when an user requests the content of a page.

- - ### Method Detail

    - #### beforeRemove

          boolean beforeRemove​(Execution exec,
                               Desktop desktop,
                               int cause)

      Called when the client asks the server to remove a desktop because of the user's navigating to other URL or refreshing the page.

      The implementation can retrieve the request path by calling `Desktop.getRequestPath()`.

      Notice that, when the user refreshes a page, this method might be called after `beforeService(org.zkoss.zk.ui.Execution, java.lang.String)` is called (depending on the browser and networking). In other words, there is no way it is a brand-new request from a new window, or it is caused by user's refreshing.

      Parameters:
        `exec` - the current execution.
        `cause` - the cause. It is reserved for the future extension.
      Returns:
        whether to recycle the desktop. If true is returned, the desktop won't be removed. It is the implementation's job to remove it if necessary.

    - #### afterRemove

          void afterRemove​(Session sess,
                           Desktop desktop)

      Called after a desktop is removed. A desktop is removed for different reasons, such as a session timeout, and too many desktops (when the memory is running low). In other words, some desktops are removed directly and only `afterRemove(org.zkoss.zk.ui.Session, org.zkoss.zk.ui.Desktop)` is called.

      The implementation has to remove the cached desktop, if any.

      When this method is called, there might be no execution available (`Executions.getCurrent()` might return null).

      Parameters:
        `sess` - the session that the desktop belongs to. Notice that `Desktop.getSession()` might be null when this method is called since it is destroyed.
        `desktop` - the desktop to remove

    - #### beforeService

          Desktop beforeService​(Execution exec,
                                java.lang.String uri)

      Called when an user requests the content of a page. To reuse a desktop, this method has to return the desktop to reuse.
      Parameters:
        `exec` - the execution. It doesn't not associated with a desktop, and used only for accessing the request and response.
        `uri` - the request URI. It is a combination of `Desktop.getRequestPath()` and `Desktop.getQueryString()`. For example, if `Desktop.getRequestPath()` and `Desktop.getQueryString()` are "/foo.zul" and "abc=1", then this parameter is "/foo.zul?abc=1".
      Returns:
        the desktop to re-use. If null is returned, ZK Loader will create a desktop as if this interface is not installed.

    - #### afterService

          void afterService​(Desktop desktop)

      Called after the request is served.

      The implementation usually does nothing in this method, unless it wants to re-use it no matter if the same user might open two or more windows to visit the same URL.

      When this method is called, there might be no execution available (`Executions.getCurrent()` might return null).