Package org.zkoss.zk.ui.sys

## Interface FailoverManager

-     public interface FailoverManager

  Represents a class that is able to handle fail-over in the application specific way.

  Desktops, pages and components are serializables, so you can use the clustering feature supported by the Web server without implementing this interface. In other words, you need to implement this interface only if you want to provide an application-specific way to re-create back.

  If you want to use the Web server's clustering feature, what you need to do is to specify `SerializableUiFactory` as the UI factory in zk.xml as follows (and forget `FailoverManager`).

      <system-config>
       <ui-factory-class>org.zkoss.zk.ui.http.SerializableUiFactory</ui-factory-class>
      </system-config>

  The recovery involves two phases:

  1. `isRecoverable(org.zkoss.zk.ui.Session, java.lang.String)`: It tests whether the desktop is recoverable.
  2. `recover(org.zkoss.zk.ui.Session, org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Desktop)`: If recoverable, ZK will create the desktop accordingly, prepare the execution and then invoke this method to do real recovery.
  Author:
    tomyeh

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `isRecoverable​(Session sess, java.lang.String desktopId)` | Tests whether the specified desktop ID is recoverable.
    `void` | `recover​(Session sess, Execution exec, Desktop desktop)` | Recovers the specified desktop.
    `void` | `start​(WebApp wapp)` | Starts the failover manager.
    `void` | `stop​(WebApp wapp)` | Stops the failover manager.

- - ### Method Detail

    - #### start

          void start​(WebApp wapp)

      Starts the failover manager.
      Since:
        5.0.0

    - #### stop

          void stop​(WebApp wapp)

      Stops the failover manager. Called only if the server is about to stop.
      Since:
        5.0.0

    - #### isRecoverable

          boolean isRecoverable​(Session sess,
                                java.lang.String desktopId)

      Tests whether the specified desktop ID is recoverable.

      Note: when this method called, no execution (`Execution`) is available. The implementation shall only check whether it is possible to recover the specified desktop ID. Then, do the real recovery in `recover(org.zkoss.zk.ui.Session, org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Desktop)`.

      Parameters:
        `sess` - the session
        `desktopId` - the desktop ID to recover

    - #### recover

          void recover​(Session sess,
                       Execution exec,
                       Desktop desktop)
                throws UiException

      Recovers the specified desktop. It is called only when `isRecoverable(org.zkoss.zk.ui.Session, java.lang.String)` returns true. Before calling this method, the desktop and execution `Execution`) are all prepared.

      Note: ZK assumes the failover manager can recover the desktop completely, so it won't update the browser whatever have been done in this method.

      During the recovering process, you have to do the following:

      Recover Desktop

      - [must] Call `DesktopCtrl.setId(java.lang.String)` to correct the desktop ID.
      - [optional] Call `Desktop.setCurrentDirectory(java.lang.String)` to correct the current directory. It is the directory of the path of the ZUML page.
      - [optional] Call `Desktop.setDeviceType(java.lang.String)` to correct the device type (default: html).
      - [Must] Recover all pages and components.
      - [Optional] Recover the response ID by use of `DesktopCtrl.setResponseId(int)`.
      - [Optional] Recover desktop's attributes.

      Recover Page

      - [Must] Invoke `PageImpl(org.zkoss.zk.ui.metainfo.LanguageDefinition, org.zkoss.zk.ui.metainfo.ComponentDefinitionMap, String, String)` (or your own implementation) to create an instance of `Page`.
      - [Must] Then, invoke `PageCtrl.init(org.zkoss.zk.ui.sys.PageConfig)` to initialized the page.
      - [Optional] Recover page's attributes.
      Throws:
        `UiException` - if failed to recover