Package org.zkoss.zkex.ui.comet

## Class CometServerPush

- java.lang.Object
- - org.zkoss.zkex.ui.comet.CometServerPush

- All Implemented Interfaces:
    `ServerPush`
  Direct Known Subclasses:
    `CometServerPush`

      public class CometServerPush
      extends java.lang.Object
      implements ServerPush

  A server-push implementation that is based on comet. This implementation is compatible with any version of Servlet. It also means it doesn't utilize Servlet 3 asynchronous processing support. If you are using Servlet 3 servers, it is recommended to use `CometServerPush` instead.

  Available in ZK PE.

  Since:
    6.0.0
  Author:
    tomyeh

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static interface` | `CometServerPush.AsyncInfo` | The interface for implementing asynchronous processing.
    `protected static class` | `CometServerPush.ThreadInfo` | The info of a server-push thread.

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `activate​(long timeout)` | Activate the current thread (which must be a server-push thread).
    `protected void` | `beforeUpdate​(CometServerPush.ThreadInfo info)` |
    `boolean` | `deactivate​(boolean stop)` | Deactivates the current thread (which must be a server-push thread).
    `Desktop` | `getDesktop()` | Returns the desktop that this server push belongs to (never null).
    `protected int` | `getIntPref​(java.lang.String key)` | Retrieve the integer preference by the given key.
    `protected java.lang.String` | `getStartScript()` | Returns the JavaScript codes to enable (a.k.a., start) the server push.
    `protected java.lang.String` | `getStartScript​(java.lang.String zkediton)` |
    `protected java.lang.String` | `getStopScript()` | Returns the JavaScript codes to disable (a.k.a., stop) the server push.
    `boolean` | `isActive()` | Returns if the working thread of the server push is active.
    `void` | `onPiggyback()` | Called when `Events.ON_PIGGYBACK` is received.
    `protected void` | `onStart()` | Called when `start(org.zkoss.zk.ui.Desktop)` is called.
    `protected void` | `onStop()` | Called when `stop()` is called.
    `protected void` | `processRequest​(Execution exec, CometServerPush.AsyncInfo ai)` | Called when receiving the comet request from the client.
    `void` | `resume()` | ZK-1777 resume serverpush after DesktopRecycling
    `<T extends Event> void` | `schedule​(EventListener<T> listener, T event, Scheduler<T> scheduler)` | Called by the associated desktop to schedule a task to execute asynchronously.
    `protected boolean` | `setBusy()` | Sets busy and return if it is busy for processing other request.
    `void` | `start​(Desktop desktop)` | Starts the server push.
    `protected void` | `startClientPush()` | Sends an AU response to the client to start the server push.
    `void` | `stop()` | Stops the server push.
    `protected void` | `stopClientPush()` | Sends an AU response the client to stop the server push.

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

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

- - ### Constructor Detail

    - #### CometServerPush

          public CometServerPush()

  - ### Method Detail

    - #### startClientPush

          protected void startClientPush()

      Sends an AU response to the client to start the server push. It is called by `start(org.zkoss.zk.ui.Desktop)`.

      The derived class usually overrides this method to support different devices.

      The default implementation is to send an `AuScript` response to contain the script specified in a preference called `CometServerPush.start`, or the script returned by `getStartScript()`, if the preference is not found. Devices that don't support scripts could override this method to send a custom AU response (`AuResponse`).

    - #### stopClientPush

          protected void stopClientPush()

      Sends an AU response the client to stop the server push.

      The derived class usually overrides this method to support different devices, such as ZK Mobile.

      The default implementation is to send an `AuScript` instance to contain the script specified in a preference called `CometServerPush.stop`,' or the script returned by `getStopScript()`, if the preference is not found. Devices that don't support scripts could override this method to send a custom AU response (`AuResponse`).

    - #### getStartScript

          protected java.lang.String getStartScript()

      Returns the JavaScript codes to enable (a.k.a., start) the server push. It is called by `startClientPush()` to prepare the script of `AuScript` that will be sent to the client.

    - #### getStartScript

          protected java.lang.String getStartScript​(java.lang.String zkediton)

    - #### getIntPref

          protected int getIntPref​(java.lang.String key)

      Retrieve the integer preference by the given key. Visibility set to protected so that zkmax can have access to this method.

    - #### getStopScript

          protected java.lang.String getStopScript()

      Returns the JavaScript codes to disable (a.k.a., stop) the server push. It is called by `stopClientPush()` to prepare the script of `AuScript` that will be sent to the client.

    - #### getDesktop

          public Desktop getDesktop()

      Returns the desktop that this server push belongs to (never null).

    - #### isActive

          public boolean isActive()

      Description copied from interface: `ServerPush`
      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)`.
      Specified by:
        `isActive` in interface `ServerPush`

    - #### start

          public void start​(Desktop desktop)

      Starts the server push.

      The derived class rarely need to override this method. Rather, override `startClientPush()`.

      Specified by:
        `start` in interface `ServerPush`

    - #### resume

          public void resume()

      ZK-1777 resume serverpush after DesktopRecycling
      Specified by:
        `resume` in interface `ServerPush`

    - #### stop

          public void stop()

      Stops the server push.

      The derived class rarely need to override this method. Rather, override `stopClientPush()`.

      Specified by:
        `stop` in interface `ServerPush`

    - #### onStart

          protected void onStart()

      Called when `start(org.zkoss.zk.ui.Desktop)` is called. This method is called before `startClientPush()`, and used to initialize the desktop, if necessary.

      The default implementation initializes an extension to process the comet request.

    - #### onStop

          protected void onStop()

      Called when `stop()` is called. This method is called after `stopClientPush()` is called and this server push has been cleaned up.

      The default implementation does nothing.

    - #### onPiggyback

          public void onPiggyback()

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

      Specified by:
        `onPiggyback` in interface `ServerPush`

    - #### schedule

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

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

      Specified by:
        `schedule` in interface `ServerPush`
      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.
        `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.

    - #### setBusy

          protected boolean setBusy()

      Sets busy and return if it is busy for processing other request. If it is busy, true is returned. If it is not busy, false is returned but it is marked as busy.

      It is possible since the client might abort the previous one and issue a new one but their server didn't know.

    - #### processRequest

          protected void processRequest​(Execution exec,
                                        CometServerPush.AsyncInfo ai)
                                 throws java.io.IOException

      Called when receiving the comet request from the client.
      Throws:
        `java.io.IOException`

    - #### activate

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

      Description copied from interface: `ServerPush`
      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 `ServerPush.deactivate(boolean)` in this finally clause.

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

      Unlike `ServerPush.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.

      Specified by:
        `activate` in interface `ServerPush`
      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).

    - #### beforeUpdate

          protected void beforeUpdate​(CometServerPush.ThreadInfo info)

    - #### deactivate

          public boolean deactivate​(boolean stop)

      Description copied from interface: `ServerPush`
      Deactivates the current thread (which must be a server-push thread).
      Specified by:
        `deactivate` in interface `ServerPush`
      Parameters:
        `stop` - whether to stop after deactivate
      Returns:
        true if it is stopped
      See Also:
        `ServerPush.activate(long)`