Package org.zkoss.zk.ui.util

## Interface PerformanceMeter

-     public interface PerformanceMeter

  An application-level listener to measure the performance of the processing of client requests.

  Note: ZK doesn't fork another low-priority thread to call the methods defined in this listener. It is the implementation's job to minimize the overhead when calculating the performance data.

  There are two kind of requests: loading a page (regular HTTP requests) and AU updates (a.k.a., Ajax requests). When loading a page, `requestStartAtClient(java.lang.String, org.zkoss.zk.ui.Execution, long)` might not be called (since the browser doesn't carry the initial time in the request), and the request ID will be the desktop's ID. For AU updates, `requestStartAtClient(java.lang.String, org.zkoss.zk.ui.Execution, long)` must be called and the request ID a desktop-wide unique ID to identify a request.

  To monitor the performance of each event and execution, you can also implement `ExecutionMonitor`.

  Since:
    3.0.0
  Author:
    tomyeh

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `requestCompleteAtClient​(java.lang.String requestId, Execution exec, long time)` | Called to notify when the client has completed the processing of the response.
    `void` | `requestCompleteAtServer​(java.lang.String requestId, Execution exec, long time)` | Called to notify when the server has completed the processing of the request.
    `void` | `requestReceiveAtClient​(java.lang.String requestId, Execution exec, long time)` | Called to notify when the client has received the response (but not processed yet).
    `void` | `requestStartAtClient​(java.lang.String requestId, Execution exec, long time)` | Called to notify when the client starts to send the request to server.
    `void` | `requestStartAtServer​(java.lang.String requestId, Execution exec, long time)` | Called to notify when the server receives the request.

- - ### Method Detail

    - #### requestStartAtClient

          void requestStartAtClient​(java.lang.String requestId,
                                    Execution exec,
                                    long time)

      Called to notify when the client starts to send the request to server.
      Parameters:
        `requestId` - a desktop-wide unique ID to identify a request. Note: it is not the same as `ExecutionCtrl.getRequestId()`
        `exec` - the execution. You can retrieve the desktop, session and user's info from it. But, don't access the component in this method since it is not safe (exec is not activated).
        `time` - the time representing the number of milliseconds between midnight January 1, 1970 (UTC) to when the client starts the request. It is client's time, not server's.

    - #### requestReceiveAtClient

          void requestReceiveAtClient​(java.lang.String requestId,
                                      Execution exec,
                                      long time)

      Called to notify when the client has received the response (but not processed yet).

      Note: the invocation of this method doesn't take place immediately. Rather it is piggyback when the client is sending another request. It also means that this method might not be called for each request (due to no further request).

      Note to version prior to 3.0.8:
      This method is introduced since 3.0.8. Prior to 3.0.8, `requestCompleteAtClient(java.lang.String, org.zkoss.zk.ui.Execution, long)` is actually the time when the client received the response rather than when the response has been processed.

      Parameters:
        `requestId` - a desktop-wide unique ID to identify a request. If `requestStartAtClient(java.lang.String, org.zkoss.zk.ui.Execution, long)` was called, it is the same as the request ID that was passed to `requestStartAtClient(java.lang.String, org.zkoss.zk.ui.Execution, long)`, If not called, it is the desktop's ID.
        `exec` - the execution. You can retrieve the desktop, session and user's info from it. But, don't access the component in this method since it is not safe (exec is not activated).
        `time` - the time representing the number of milliseconds between midnight January 1, 1970 (UTC) to when the client has completed the process. It is client's time, not server's.
      Since:
        3.0.8

    - #### requestCompleteAtClient

          void requestCompleteAtClient​(java.lang.String requestId,
                                       Execution exec,
                                       long time)

      Called to notify when the client has completed the processing of the response.

      Note: the invocation of this method doesn't take place immediately. Rather it is piggyback when the client is sending another request. It also means that this method might not be called for each request (due to no further request).

      Parameters:
        `requestId` - a desktop-wide unique ID to identify a request. If `requestStartAtClient(java.lang.String, org.zkoss.zk.ui.Execution, long)` was called, it is the same as the request ID that was passed to `requestStartAtClient(java.lang.String, org.zkoss.zk.ui.Execution, long)`, If not called, it is the desktop's ID.
        `exec` - the execution. You can retrieve the desktop, session and user's info from it. But, don't access the component in this method since it is not safe (exec is not activated).
        `time` - the time representing the number of milliseconds between midnight January 1, 1970 (UTC) to when the client has completed the process. It is client's time, not server's.

    - #### requestStartAtServer

          void requestStartAtServer​(java.lang.String requestId,
                                    Execution exec,
                                    long time)

      Called to notify when the server receives the request.
      Parameters:
        `requestId` - a desktop-wide unique ID to identify a request. If `requestStartAtClient(java.lang.String, org.zkoss.zk.ui.Execution, long)` was called, it is the same as the request ID that was passed to `requestStartAtClient(java.lang.String, org.zkoss.zk.ui.Execution, long)`, If not called, it is the desktop's ID.
        `exec` - the execution. You can retrieve the desktop, session and user's info from it. But, don't access the component in this method since it is not safe (exec is not activated).
        `time` - the time representing the number of milliseconds between midnight January 1, 1970 (UTC) to when the server receives the request. It is server's time.

    - #### requestCompleteAtServer

          void requestCompleteAtServer​(java.lang.String requestId,
                                       Execution exec,
                                       long time)

      Called to notify when the server has completed the processing of the request.
      Parameters:
        `requestId` - a desktop-wide unique ID to identify a request. If `requestStartAtClient(java.lang.String, org.zkoss.zk.ui.Execution, long)` was called, it is the same as the request ID that was passed to `requestStartAtClient(java.lang.String, org.zkoss.zk.ui.Execution, long)`, If not called, it is the desktop's ID.
        `exec` - the execution. You can retrieve the desktop, session and user's info from it. But, don't access the component in this method since it is not safe (exec is not activated).
        `time` - the time representing the number of milliseconds between midnight January 1, 1970 (UTC) to when the server has completed the process. It is server's time.