Package org.zkoss.zk.ui.sys

## Interface ServerPush

- All Known Implementing Classes:
    `CometServerPush`, `CometServerPush`, `PollingServerPush`, `WebSocketServerPush`

      public interface ServerPush

  Represents a server-push controller. A server-push controller is a plugin to provide the server-push feature for ZK. A server-push thread is a working thread that want to manipulate a desktop whenever it wants, rather than in an event listener.

  There are several to implement (or, to simulate) the server-push feature on a HTTP-based application.

  First, the server-push feature can be simulated by client's polling. That is, the client polls the server for executing any pending server-push threads. The client can adjust the frequency based on the response time (in proportion to the server load) (see `PollingServerPush` for details). To poll, the client usually send the dummy command that does nothing but trigger `onPiggyback()` to be execute.

  Second, the server-push feature can be implemented by maintaining a persistent connection between client and server. It is also called Comet (see also Comet).

  Third, the server-push feature can be simulated in a passive way. That is, it doesn't poll at all. Rather `onPiggyback()` is called automatically when the user trigger some other events.

  Since:
    3.0.0
  Author:
    tomyeh

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `activate​(long timeout)` | Activate the current thread (which must be a server-push thread).
    `boolean` | `deactivate​(boolean stop)` | Deactivates the current thread (which must be a server-push thread).
    `boolean` | `isActive()` | Returns if the working thread of the server push is active.
    `void` | `onPiggyback()` | Called when `Events.ON_PIGGYBACK` is received.
    `void` | `resume()` | Resumes server-push - this is required after desktop recycling.
    `<T extends Event> void` | `schedule​(EventListener<T> task, T event, Scheduler<T> scheduler)` | Called by the associated desktop to schedule a task to execute asynchronously.
    `void` | `start​(Desktop desktop)` | Starts and initializes the server-push controller.
    `void` | `stop()` | Stops and cleans up the server-push controller.

- - ### Method Detail

    - #### isActive

          boolean isActive()

      Returns if the working thread of the server push is active. In other words, it is true if it is between `Executions.activate(org.zkoss.zk.ui.Desktop)` and `Executions.deactivate(org.zkoss.zk.ui.Desktop)`.
      Since:
        3.5.2

    - #### start

          void start​(Desktop desktop)

      Starts and initializes the server-push controller. One server-push controller is associated with exactly one desktop.

      `start(org.zkoss.zk.ui.Desktop)` is called when `Desktop.enableServerPush(boolean)` is called to enable the server-push feature for the specified desktop.

    - #### stop

          void stop()

      Stops and cleans up the server-push controller.

      `stop()` is called when `Desktop.enableServerPush(boolean)` is called to disable the server-push feature, or when the desktop is being removed.

    - #### resume

          void resume()

      Resumes server-push - this is required after desktop recycling. (added ServerPush interface to fix ZK-1777)

      `resume()` is called when `UiEngine.recycleDesktop(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Page, java.io.Writer)` is called to resume a previously enabled server-push on the recycled desktop.

      Since:
        6.5.4

    - #### schedule

          <T extends Event> void schedule​(EventListener<T> task,
                                          T event,
                                          Scheduler<T> scheduler)

      Called by the associated desktop to schedule a task to execute asynchronously.

      The implementation usually delegates the scheduling to the scheduler passed as the third argument, which is controlled by the desktop. Of course, it could schedule it by itself.

      Parameters:
        `task` - 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.
        `scheduler` - the default scheduler to schedule the task. The implementation usually delegates the scheduling back to it. If you prefer to handle it by yourself, you could ignore it.
      Since:
        5.0.6

    - #### activate

          boolean activate​(long timeout)
                    throws java.lang.InterruptedException,
                           DesktopUnavailableException

      Activate the current thread (which must be a server-push thread). It causes the current thread to wait until the desktop is available to access, the desktop no longer exists, some other thread interrupts this thread, or a certain amount of real time has elapsed.

      The invoker of this method must invoke `deactivate(boolean)` in this finally clause.

      Note: the activation is applied to the desktop that was assigned by `start(org.zkoss.zk.ui.Desktop)`.

      Unlike `onPiggyback()`, this method is NOT called in the context of an event listener. Rather, it is called in the thread of a server-push thread.

      Parameters:
        `timeout` - the maximum time to wait in milliseconds. Ignored (i.e., never timeout) if non-positive.
      Returns:
        whether it is activated or it is timeout. The only reason it returns false is timeout.
      Throws:
        `java.lang.InterruptedException` - if it is interrupted by other thread
        `DesktopUnavailableException` - if the desktop is removed (when activating).

    - #### deactivate

          boolean deactivate​(boolean stop)

      Deactivates the current thread (which must be a server-push thread).
      Parameters:
        `stop` - whether to stop after deactivate
      Returns:
        true if it is stopped
      Since:
        3.5.2
      See Also:
        `activate(long)`

    - #### onPiggyback

          void onPiggyback()

      Called when `Events.ON_PIGGYBACK` is received. The invocation is passive (i.e., triggered by other events, rather than spontaneous).

      This method is called in the context of an event listener. In other words, the execution is activated and you can retrieve it by `Executions.getCurrent()`.