Package org.zkoss.zkmax.ui.util

## Class DesktopRecycle

- java.lang.Object
- - org.zkoss.zkmax.ui.util.DesktopRecycle

- All Implemented Interfaces:
    `DesktopRecycle`

      public class DesktopRecycle
      extends java.lang.Object
      implements DesktopRecycle

  Used to recycle the desktop if possible.

  Available in ZK EE

  If you want to recycle only particular paths, you could override `shallCache(org.zkoss.zk.ui.Desktop, java.lang.String, int)` and `shallReuse(org.zkoss.zk.ui.Desktop, java.lang.String, int)`.

  Since:
    5.0.0
  Author:
    tomyeh

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DesktopRecycle()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete 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.
    `protected static java.lang.String` | `getURI​(Desktop desktop)` | Returns the request URI of the desktop.
    `protected java.util.Map` | `newCache​(Session sess)` | Instantiates the cache to hold the recycled desktop for the given session.
    `protected boolean` | `shallCache​(Desktop desktop, java.lang.String uri, int cause)` | Returns whether to cache the desktop of the specified URI, such that we can reuse it later.
    `protected boolean` | `shallExpunge​(Desktop desktop, java.lang.String uri, int secElapsed)` | Returns whether to remove it from the cache.
    `protected boolean` | `shallReuse​(Desktop desktop, java.lang.String uri, int secElapsed)` | Returns whether to re-use the cached desktop.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### DesktopRecycle

          public DesktopRecycle()

  - ### Method Detail

    - #### beforeRemove

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

      Description copied from interface: `DesktopRecycle`
      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 `DesktopRecycle.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.

      Specified by:
        `beforeRemove` in interface `DesktopRecycle`
      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.

    - #### getURI

          protected static java.lang.String getURI​(Desktop desktop)

      Returns the request URI of the desktop. 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".
      Since:
        5.0.2

    - #### afterRemove

          public void afterRemove​(Session sess,
                                  Desktop desktop)

      Description copied from interface: `DesktopRecycle`
      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 `DesktopRecycle.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).

      Specified by:
        `afterRemove` in interface `DesktopRecycle`
      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

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

      Description copied from interface: `DesktopRecycle`
      Called when an user requests the content of a page. To reuse a desktop, this method has to return the desktop to reuse.
      Specified by:
        `beforeService` in interface `DesktopRecycle`
      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

          public void afterService​(Desktop desktop)

      Description copied from interface: `DesktopRecycle`
      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).

      Specified by:
        `afterService` in interface `DesktopRecycle`

    - #### newCache

          protected java.util.Map newCache​(Session sess)

      Instantiates the cache to hold the recycled desktop for the given session.

      Default: instantiate a hash map.

      Since:
        5.0.7

    - #### shallCache

          protected boolean shallCache​(Desktop desktop,
                                       java.lang.String uri,
                                       int cause)

      Returns whether to cache the desktop of the specified URI, such that we can reuse it later.

      The default implementation always return true. It means it tries to cache all paths.

      If you want to cache only for, say, "/long-op/*", you can return true if path.startsWith("/long-op/").

      Parameters:
        `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".

    - #### shallReuse

          protected boolean shallReuse​(Desktop desktop,
                                       java.lang.String uri,
                                       int secElapsed)

      Returns whether to re-use the cached desktop.

      The default implementation return true if the page was served in 10 minutes (600 seconds).

      Parameters:
        `secElapsed` - the number of seconds elapsed since the page was served.

    - #### shallExpunge

          protected boolean shallExpunge​(Desktop desktop,
                                         java.lang.String uri,
                                         int secElapsed)

      Returns whether to remove it from the cache. It is called if `shallReuse(org.zkoss.zk.ui.Desktop, java.lang.String, int)` returns false.

      Default: return true if the page was served more than 10 minutes ago (i.e., too old and we have to expunge it).

      Since:
        5.0.7