Package org.zkoss.zk.ui.sys

## Interface ExecutionCtrl

- All Known Implementing Classes:
    `AbstractExecution`, `ExecutionImpl`

      public interface ExecutionCtrl

  Additional interface to `Execution` for implementation.

  Application developers shall never access any of this methods.

  Author:
    tomyeh

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addOnActivate​(Callback callback)` | Adds a callback method to be executed only once after the execution activated.
    `void` | `addOnDeactivate​(Callback callback)` | Adds a callback method to be executed only once after the execution being deactivated (i.e. do the callback in `onBeforeDeactivate()`.
    `Page` | `getCurrentPage()` | Returns the current page.
    `PageDefinition` | `getCurrentPageDefinition()` | Returns the current page definition, which is pushed when evaluating a page (from a page definition).
    `ExecutionInfo` | `getExecutionInfo()` | Returns the information of the event being served, or null if the execution is not under serving an event.
    `java.lang.Object` | `getExtraXelVariable​(java.lang.String name)` | Returns the object, if any, defined in any variable resolver added by `Execution.addVariableResolver(org.zkoss.xel.VariableResolver)`.
    `java.lang.Object` | `getExtraXelVariable​(XelContext ctx, java.lang.Object base, java.lang.Object name)` | Returns the object, if any, defined in any variable resolver added by `Execution.addVariableResolver(org.zkoss.xel.VariableResolver)`.
    `Event` | `getNextEvent()` | Returns the next event queued by `Execution.postEvent(org.zkoss.zk.ui.event.Event)`, or null if no event queued.
    `java.lang.String` | `getRequestId()` | Returns the sequence ID of the current request, or null if not available.
    `java.util.Collection<AuResponse>` | `getResponses()` | Returns the collection of the AU responses (`AuResponse`) that shall be generated to the output, or null if not available.
    `Visualizer` | `getVisualizer()` | Returns the `Visualizer` for this execution.
    `boolean` | `isActivated()` | Returns whether this execution is activated.
    `boolean` | `isRecovering()` | Returns whether this execution is in recovering.
    `void` | `onActivate()` | Called when this execution is about to become the current execution `Executions.getCurrent()`.
    `void` | `onBeforeDeactivate()` | Called when this execution is about to become a non-current execution.
    `void` | `onDeactivate()` | Called when this execution is about to become a non-current execution.
    `void` | `setContentType​(java.lang.String contentType)` | Sets the content type.
    `void` | `setCurrentPage​(Page page)` | Sets the current page.
    `void` | `setCurrentPageDefinition​(PageDefinition pgdef)` | Sets the current page definition.
    `void` | `setDesktop​(Desktop desktop)` | Sets the desktop associated with this execution.
    `void` | `setExecutionInfo​(ExecutionInfo evtinf)` | Sets the information of the event being served, or null if not under serving an event.
    `void` | `setRequestId​(java.lang.String reqId)` | Sets the sequence ID of the current request.
    `void` | `setResponses​(java.util.Collection<AuResponse> responses)` | Sets the collection of the AU responses (`AuResponse`) that shall be generated to the output.

- - ### Method Detail

    - #### getCurrentPage

          Page getCurrentPage()

      Returns the current page. Though an execution might process many pages, it processes update requests one-by-one and each update request is associated with a page.

      Design decision: we put it here because user need not to know about the concept of the current page.

      Since 3.6.0, this method returns the first page if `setCurrentPage(org.zkoss.zk.ui.Page)` was not called (such as Server Push).

      See Also:
        `Desktop.getPage(java.lang.String)`

    - #### setCurrentPage

          void setCurrentPage​(Page page)

      Sets the current page. Though an execution might process many pages, it processes update requests one-by-one and each update request is associated with a page.

    - #### getCurrentPageDefinition

          PageDefinition getCurrentPageDefinition()

      Returns the current page definition, which is pushed when evaluating a page (from a page definition).

    - #### setCurrentPageDefinition

          void setCurrentPageDefinition​(PageDefinition pgdef)

      Sets the current page definition.
      Parameters:
        `pgdef` - the page definition. If null, it means it is the same as getCurrentPage().getPageDefinition().

    - #### getNextEvent

          Event getNextEvent()

      Returns the next event queued by `Execution.postEvent(org.zkoss.zk.ui.event.Event)`, or null if no event queued.

      Implementation Notes: `Execution.postEvent(int,Component,Event)` proxies the event with `ProxyEvent` if the real target is different from `Event.getTarget()`. Of course, it is transparent to the event listeners since the real event will be passed to the listener (rather than the proxy event).

    - #### isActivated

          boolean isActivated()

      Returns whether this execution is activated.

    - #### onActivate

          void onActivate()

      Called when this execution is about to become the current execution `Executions.getCurrent()`.

      Note: an execution might spread over several threads, so this method might be called several times to activate the states in each thread. Also, an execution might be activated before another is deactivate. For example, when a component includes another page, the second exec is activated to render the included page.

      It is used as callback notification.

      Note: don't throw any exception in this method.

    - #### onDeactivate

          void onDeactivate()

      Called when this execution is about to become a non-current execution.

      It is used as callback notification.

      Note: don't throw any exception in this method.

      See Also:
        `onActivate()`

    - #### onBeforeDeactivate

          void onBeforeDeactivate()

      Called when this execution is about to become a non-current execution.

      It is used as callback notification.

      Note: don't throw any exception in this method.

      Since:
        7.0.5
      See Also:
        `onDeactivate()`

    - #### addOnActivate

          void addOnActivate​(Callback callback)

      Adds a callback method to be executed only once after the execution activated.
      Parameters:
        `callback` -
      Since:
        7.0.5

    - #### addOnDeactivate

          void addOnDeactivate​(Callback callback)

      Adds a callback method to be executed only once after the execution being deactivated (i.e. do the callback in `onBeforeDeactivate()`.
      Parameters:
        `callback` -
      Since:
        7.0.5

    - #### isRecovering

          boolean isRecovering()

      Returns whether this execution is in recovering. In other words, it is in the invocation of `FailoverManager.recover(org.zkoss.zk.ui.Session, org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Desktop)`. If in recovering, no response is sent to the client. It assumes the server is recovering the desktop and all it contains to match the client's status.

    - #### getVisualizer

          Visualizer getVisualizer()

      Returns the `Visualizer` for this execution. It is the same as `DesktopCtrl.getVisualizer()`.

    - #### setContentType

          void setContentType​(java.lang.String contentType)

      Sets the content type.
      Since:
        5.0.0

    - #### setDesktop

          void setDesktop​(Desktop desktop)

      Sets the desktop associated with this execution. You rarely need to use this method, since the desktop is associated when this execution is created.

      Currently, it is used to communicate between WebManager.newDesktop and DesktopImpl's constructor.

      Throws:
        `java.lang.IllegalArgumentException` - if desktop is null
        `java.lang.IllegalStateException` - if there is already a desktop is associated with it.
      Since:
        3.0.0

    - #### setRequestId

          void setRequestId​(java.lang.String reqId)

      Sets the sequence ID of the current request.
      Since:
        3.0.5

    - #### getRequestId

          java.lang.String getRequestId()

      Returns the sequence ID of the current request, or null if not available. Not all clients support the request ID.
      Since:
        3.0.5

    - #### getResponses

          java.util.Collection<AuResponse> getResponses()

      Returns the collection of the AU responses (`AuResponse`) that shall be generated to the output, or null if not available.
      Since:
        5.0.0

    - #### setResponses

          void setResponses​(java.util.Collection<AuResponse> responses)

      Sets the collection of the AU responses (`AuResponse`) that shall be generated to the output.
      Since:
        5.0.0

    - #### getExecutionInfo

          ExecutionInfo getExecutionInfo()

      Returns the information of the event being served, or null if the execution is not under serving an event.

      Unlike most of other methods, this method could be accessed by another thread.

      Since:
        5.0.6

    - #### setExecutionInfo

          void setExecutionInfo​(ExecutionInfo evtinf)

      Sets the information of the event being served, or null if not under serving an event.
      Since:
        5.0.6

    - #### getExtraXelVariable

          java.lang.Object getExtraXelVariable​(java.lang.String name)

      Returns the object, if any, defined in any variable resolver added by `Execution.addVariableResolver(org.zkoss.xel.VariableResolver)`.

      Notice that it looks only for the variables defined in `Execution.addVariableResolver(org.zkoss.xel.VariableResolver)`. To get a variable an EL expression can reference, please use `Execution.getVariableResolver()` instead.

      Since:
        6.0.0

    - #### getExtraXelVariable

          java.lang.Object getExtraXelVariable​(XelContext ctx,
                                               java.lang.Object base,
                                               java.lang.Object name)

      Returns the object, if any, defined in any variable resolver added by `Execution.addVariableResolver(org.zkoss.xel.VariableResolver)`.

      Notice that it looks only for the variables defined in `Execution.addVariableResolver(org.zkoss.xel.VariableResolver)`. To get a variable an EL expression can reference, please use `Execution.getVariableResolver()` instead.

      Unlike `getExtraXelVariable(String)`, this method can utilize `VariableResolverX` if you'd like to retrieve a property of another object.

      Parameters:
        `ctx` - the XEL context
        `base` - the base object. If null, it looks for a top-level variable. If not null, it looks for a member of the base object (such as getter).
        `name` - the property to retrieve.
      Since:
        6.0.0
      See Also:
        `getExtraXelVariable(String)`