Package org.zkoss.zk.ui

## Class Executions

- java.lang.Object
- - org.zkoss.zk.ui.Executions

- Direct Known Subclasses:
    `ExecutionsCtrl`

      public class Executions
      extends java.lang.Object

  Utilities to access `Execution`.
  Author:
    tomyeh

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected static java.lang.ThreadLocal<Execution>` | `_exec` | Stores the current `Execution`.

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static void` | `activate​(Desktop desktop)` | Activates a thread to allow it access the given desktop synchronously.
    `static boolean` | `activate​(Desktop desktop, long timeout)` | Activates a thread to allow it access the given desktop synchronously, or until a certain amount of time has elapsed.
    `static Component` | `createComponents​(java.lang.String uri, Component parent, java.util.Map<?,​?> arg)` | Creates components from a page file specified by an URI.
    `static Component[]` | `createComponents​(java.lang.String uri, Page page, VariableResolver resolver, java.util.Map<?,​?> arg)` | Creates components that belong to the given page from a page file specified by an URI.
    `static Component` | `createComponents​(PageDefinition pagedef, Component parent, java.util.Map<?,​?> arg)` | Creates components based on the specified page definition.
    `static Component[]` | `createComponents​(WebApp wapp, java.lang.String uri, java.util.Map<?,​?> arg)` | Creates components that don't belong to any page from a page file specified by an URI.
    `static Component[]` | `createComponents​(WebApp wapp, PageDefinition pagedef, java.util.Map<?,​?> arg)` | Creates components that don't belong to any page from the specified page definition.
    `static Component` | `createComponentsDirectly​(java.io.Reader reader, java.lang.String extension, Component parent, java.util.Map<?,​?> arg)` | Creates components from the raw content read from the specified reader.
    `static Component` | `createComponentsDirectly​(java.lang.String content, java.lang.String extension, Component parent, java.util.Map<?,​?> arg)` | Creates components from the raw content specified by a string.
    `static Component` | `createComponentsDirectly​(Document content, java.lang.String extension, Component parent, java.util.Map<?,​?> arg)` | Creates components from the raw content specified by a DOM tree.
    `static Component[]` | `createComponentsDirectly​(WebApp wapp, java.io.Reader reader, java.lang.String extension, java.util.Map<?,​?> arg)` | Creates components that don't belong to any page from the raw content read from the specified reader.
    `static Component[]` | `createComponentsDirectly​(WebApp wapp, java.lang.String content, java.lang.String extension, java.util.Map<?,​?> arg)` | Creates components that don't belong to any page from the raw content specified by a string.
    `static Component[]` | `createComponentsDirectly​(WebApp wapp, Document content, java.lang.String extension, java.util.Map<?,​?> arg)` | Creates components that don't belong to any page from the raw content specified by a DOM tree.
    `static void` | `deactivate​(Desktop desktop)` | Deactivates a thread that has invoked `activate(org.zkoss.zk.ui.Desktop)` successfully.
    `static java.net.URL` | `encodeToURL​(java.lang.String uri)` | Encodes the specified URL into an instance of `URL`.
    `static java.lang.String` | `encodeURL​(java.lang.String uri)` | Encodes the specified URL.
    `static java.lang.Object` | `evaluate​(Component comp, java.lang.String expr, java.lang.Class expectedType)` | Evaluates the specified expression by use of the current context (`getCurrent()`).
    `static java.lang.Object` | `evaluate​(Page page, java.lang.String expr, java.lang.Class expectedType)` | Evaluates the specified expression with the resolver of the current execution (`getCurrent()`).
    `static void` | `forward​(java.lang.String page)` | A shortcut of Executions.getCurrent().forward(page).
    `static Execution` | `getCurrent()` | Returns the current execution.
    `static Evaluator` | `getEvaluator​(Component comp, java.lang.Class<? extends ExpressionFactory> expfcls)` | Returns the evaluator of the current execution.
    `static Evaluator` | `getEvaluator​(Page page, java.lang.Class<? extends ExpressionFactory> expfcls)` | Returns the evaluator of the current execution.
    `static PageDefinition` | `getPageDefinition​(WebApp wapp, java.lang.String uri)` | Returns the page definition from the page file specified by an URI.
    `PageDefinition` | `getPageDefinitionDirectly​(WebApp wapp, java.io.Reader reader, java.lang.String extension)` | Reads the raw content from a reader and converts it into a page definition.
    `PageDefinition` | `getPageDefinitionDirectly​(WebApp wapp, java.lang.String content, java.lang.String extension)` | Converts the specified page content to a page definition.
    `PageDefinition` | `getPageDefinitionDirectly​(WebApp wapp, Document content, java.lang.String extension)` | Converts the specified page content, in DOM, to a page definition.
    `static void` | `include​(java.lang.String page)` | A shortcut of Executions.getCurrent().include(page).
    `static void` | `notify​(java.lang.Object mutex)` | Wakes up a single event processing thread that is waiting on the specified object.
    `static void` | `notify​(Desktop desktop, java.lang.Object mutex)` | Wakes up a single event processing thread for the specified desktop that is waiting on the specified object.
    `static void` | `notifyAll​(java.lang.Object mutex)` | Wakes up all event processing thread that are waiting on the specified object.
    `static void` | `notifyAll​(Desktop desktop, java.lang.Object mutex)` | Wakes up all event processing threads for the specified desktop that are waiting on the specified object.
    `static <T extends Event> void` | `schedule​(Desktop desktop, EventListener<T> task, T event)` | Schedules a task to run under the server push of the given desktop asynchronously.
    `static void` | `sendRedirect​(java.lang.String uri)` | Sends a temporary redirect response to the client using the specified redirect location URL by use of the current execution, `getCurrent()`.
    `static void` | `wait​(java.lang.Object mutex)` | Suspends the current processing of an event and wait until the other thread invokes `notify(Object)`, `notifyAll(Object)`, `notify(Desktop, Object)` or `notifyAll(Desktop, Object)` for the specified object.

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

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

- - ### Field Detail

    - #### _exec

          protected static final java.lang.ThreadLocal<Execution> _exec

      Stores the current `Execution`.

  - ### Constructor Detail

    - #### Executions

          public Executions()

  - ### Method Detail

    - #### getCurrent

          public static final Execution getCurrent()

      Returns the current execution.

    - #### getEvaluator

          public static final Evaluator getEvaluator​(Page page,
                                                     java.lang.Class<? extends ExpressionFactory> expfcls)

      Returns the evaluator of the current execution. It is usually used to parse the expression into `Expression` or used with `ExValue`. for performance improvement.
      Parameters:
        `page` - the page that this evaluator is associated. If null, the current page and then the first page is assumed.
        `expfcls` - the implementation of `ExpressionFactory`, or null to use the default (`Configuration.getExpressionFactoryClass()`.
      Since:
        3.0.0

    - #### getEvaluator

          public static final Evaluator getEvaluator​(Component comp,
                                                     java.lang.Class<? extends ExpressionFactory> expfcls)

      Returns the evaluator of the current execution. It is a shortcut of getEvaluator(comp != null ? comp.getPage(): null)
      Parameters:
        `comp` - the component to retrieve the page for the evaluator
        `expfcls` - the implementation of `ExpressionFactory`, or null to use the default (`Configuration.getExpressionFactoryClass()`.
      Since:
        3.0.0

    - #### evaluate

          public static final java.lang.Object evaluate​(Component comp,
                                                        java.lang.String expr,
                                                        java.lang.Class expectedType)

      Evaluates the specified expression by use of the current context (`getCurrent()`).

      The function mapper is retrieved from component's page's function mapper (`Page.getFunctionMapper()`). If null, the current page, if any, is used to retrieve the mapper.

      For better performance, you can use the instance returned by `getEvaluator(org.zkoss.zk.ui.Page, java.lang.Class<? extends org.zkoss.xel.ExpressionFactory>)` to parse and cached the parsed expression. `ExValue` is a utility class to simply the task.

      Parameters:
        `comp` - as the self variable (ignored if null)

    - #### evaluate

          public static final java.lang.Object evaluate​(Page page,
                                                        java.lang.String expr,
                                                        java.lang.Class expectedType)

      Evaluates the specified expression with the resolver of the current execution (`getCurrent()`).

      The function mapper is retrieved from page's function mapper (`Page.getFunctionMapper()`). If null, the current page, if any, is used to retrieve the mapper.

      For better performance, you can use the instance returned by `getEvaluator(org.zkoss.zk.ui.Page, java.lang.Class<? extends org.zkoss.xel.ExpressionFactory>)` to parse and cached the parsed expression. `ExValue` is a utility class to simply the task.

      Parameters:
        `page` - used as the self variable and to retrieve the function mapper if funmap is not defined. Ignored if null.

    - #### encodeURL

          public static final java.lang.String encodeURL​(java.lang.String uri)

      Encodes the specified URL.

      It resolves "*" contained in URI, if any, to the proper Locale, and the browser code. Refer to `Servlets.locate(javax.servlet.ServletContext, ServletRequest, String, Locator)` for details.

      Throws:
        `java.lang.NullPointerException` - if the current execution is not available.
      See Also:
        `encodeURL(java.lang.String)`

    - #### encodeToURL

          public static final java.net.URL encodeToURL​(java.lang.String uri)
                                                throws java.net.MalformedURLException

      Encodes the specified URL into an instance of `URL`. It is similar to `encodeURL(java.lang.String)`, except it returns an instance of `URL`.
      Throws:
        `java.lang.NullPointerException` - if the current execution is not available.
        `java.net.MalformedURLException` - if failed to convert it to a legal `URL`
      Since:
        3.5.0

    - #### createComponents

          public static final Component createComponents​(java.lang.String uri,
                                                         Component parent,
                                                         java.util.Map<?,​?> arg)

      Creates components from a page file specified by an URI. Shortcut to `Execution.createComponents(String, Component, Map)`.
      Parameters:
        `parent` - the parent component, or null if you want it to be a root component. If parent is null, the page is assumed to be the current page, which is determined by the execution context. In other words, the new component will be the root component of the current page if parent is null.
        `arg` - a map of parameters that is accessible by the arg variable in EL, or by `Execution.getArg()`. Ignored if null.
      Returns:
        the first component being created.
      See Also:
        `createComponents(PageDefinition, Component, Map)`

    - #### createComponents

          public static final Component createComponents​(PageDefinition pagedef,
                                                         Component parent,
                                                         java.util.Map<?,​?> arg)

      Creates components based on the specified page definition. Shortcut to `Execution.createComponents(PageDefinition, Component, Map)`.
      Parameters:
        `pagedef` - the page definition to use. It cannot be null.
        `parent` - the parent component, or null if you want it to be a root component. If parent is null, the page is assumed to be the current page, which is determined by the execution context. In other words, the new component will be the root component of the current page if parent is null.
        `arg` - a map of parameters that is accessible by the arg variable in EL, or by `Execution.getArg()`. Ignored if null.
      Returns:
        the first component being created.
      See Also:
        `createComponents(String, Component, Map)`

    - #### createComponents

          public static Component[] createComponents​(WebApp wapp,
                                                     PageDefinition pagedef,
                                                     java.util.Map<?,​?> arg)

      Creates components that don't belong to any page from the specified page definition.

      Unlike `createComponents(PageDefinition,Component,Map)`, this method can be invoked without the current execution, such as a working thread. In this case, the wapp argument must be specified.

      Parameters:
        `wapp` - the Web application. It is optional and used only if no current execution (e.g., in a working thread). The instance of `WebApp` can be retrieved by use of `WebManager.getWebApp()`, while the instance of `WebManager` can be retrieved by `WebManager.getWebManager(javax.servlet.ServletContext)`
        `pagedef` - the page definition to use. It cannot be null.
        `arg` - a map of parameters that is accessible by the arg variable in EL, or by `Execution.getArg()`. Ignored if null.
      Returns:
        all top-level components being created.
      Since:
        3.6.2
      See Also:
        `createComponents(WebApp, String, Map)`

    - #### createComponents

          public static Component[] createComponents​(WebApp wapp,
                                                     java.lang.String uri,
                                                     java.util.Map<?,​?> arg)

      Creates components that don't belong to any page from a page file specified by an URI.

      It loads the page definition from the specified URI (by use `getPageDefinition(org.zkoss.zk.ui.WebApp, java.lang.String)` ), and then invokes `createComponents(WebApp,PageDefinition,Map)` to create components.

      Unlike `createComponents(String,Component,Map)`, this method can be invoked without the current execution, such as a working thread. In this case, the wapp argument must be specified.

      Parameters:
        `wapp` - the Web application. It is optional and used only if no current execution (e.g., in a working thread). The instance of `WebApp` can be retrieved by use of `WebManager.getWebApp()`, while the instance of `WebManager` can be retrieved by `WebManager.getWebManager(javax.servlet.ServletContext)`
        `arg` - a map of parameters that is accessible by the arg variable in EL, or by `Execution.getArg()`. Ignored if null.
      Returns:
        all top-level components being created.
      Since:
        3.6.2
      See Also:
        `createComponents(WebApp, PageDefinition, Map)`, `createComponentsDirectly(WebApp, String, String, Map)`, `createComponentsDirectly(WebApp, Document, String, Map)`, `createComponentsDirectly(WebApp, Reader, String, Map)`

    - #### createComponents

          public static Component[] createComponents​(java.lang.String uri,
                                                     Page page,
                                                     VariableResolver resolver,
                                                     java.util.Map<?,​?> arg)

      Creates components that belong to the given page from a page file specified by an URI.
      Parameters:
        `page` - the page, or null if you want it to attach the created components.
        `resolver` - the variable resolver used to resolve variables. Ignored if null.
        `arg` - a map of parameters that is accessible by the arg variable in EL, or by `Execution.getArg()`. Ignored if null.
      Returns:
        all top-level components being created.
      Since:
        8.0.1
      See Also:
        `createComponents(WebApp, PageDefinition, Map)`, `createComponentsDirectly(WebApp, String, String, Map)`, `createComponentsDirectly(WebApp, Document, String, Map)`, `createComponentsDirectly(WebApp, Reader, String, Map)`

    - #### createComponentsDirectly

          public static final Component createComponentsDirectly​(java.lang.String content,
                                                                 java.lang.String extension,
                                                                 Component parent,
                                                                 java.util.Map<?,​?> arg)

      Creates components from the raw content specified by a string. Shortcut to `Execution.createComponentsDirectly(String, String, Component, Map)`.
      Parameters:
        `content` - the raw content of the page. It must be a XML and compliant to the page format (such as ZUL).
        `extension` - the default extension if the content doesn't specify an language. In other words, if the content doesn't specify an language, `LanguageDefinition.getByExtension(java.lang.String)` is called. If extension is null and the content doesn't specify a language, the language called "xul/html" is assumed.
        `parent` - the parent component, or null if you want it to be a root component. If parent is null, the page is assumed to be the current page, which is determined by the execution context. In other words, the new component will be the root component of the current page if parent is null.
        `arg` - a map of parameters that is accessible by the arg variable in EL, or by `Execution.getArg()`. Ignored if null.
      Returns:
        the first component being created.
      See Also:
        `createComponents(PageDefinition, Component, Map)`, `createComponents(String, Component, Map)`, `createComponentsDirectly(Document, String, Component, Map)`, `createComponentsDirectly(Reader, String, Component, Map)`

    - #### createComponentsDirectly

          public static final Component createComponentsDirectly​(Document content,
                                                                 java.lang.String extension,
                                                                 Component parent,
                                                                 java.util.Map<?,​?> arg)

      Creates components from the raw content specified by a DOM tree. Shortcut to `Execution.createComponentsDirectly(Document, String, Component, Map)`.
      Parameters:
        `content` - the raw content in DOM.
        `extension` - the default extension if the content doesn't specify an language. In other words, if the content doesn't specify an language, `LanguageDefinition.getByExtension(java.lang.String)` is called. If extension is null and the content doesn't specify a language, the language called "xul/html" is assumed.
        `parent` - the parent component, or null if you want it to be a root component. If parent is null, the page is assumed to be the current page, which is determined by the execution context. In other words, the new component will be the root component of the current page if parent is null.
        `arg` - a map of parameters that is accessible by the arg variable in EL, or by `Execution.getArg()`. Ignored if null.
      Returns:
        the first component being created.
      See Also:
        `createComponents(PageDefinition, Component, Map)`, `createComponents(String, Component, Map)`, `createComponentsDirectly(String, String, Component, Map)`, `createComponentsDirectly(Reader, String, Component, Map)`

    - #### createComponentsDirectly

          public static Component createComponentsDirectly​(java.io.Reader reader,
                                                           java.lang.String extension,
                                                           Component parent,
                                                           java.util.Map<?,​?> arg)
                                                    throws java.io.IOException

      Creates components from the raw content read from the specified reader. Shortcut to `Execution.createComponentsDirectly(Reader, String, Component, Map)`.

      The raw content is loader and parsed to a page defintion by use of `Execution.getPageDefinitionDirectly(Reader, String)`, and then invokes `createComponents(PageDefinition,Component,Map)` to create components.

      Parameters:
        `reader` - the reader to retrieve the raw content.
        `extension` - the default extension if the content doesn't specify an language. In other words, if the content doesn't specify an language, `LanguageDefinition.getByExtension(java.lang.String)` is called. If extension is null and the content doesn't specify a language, the language called "xul/html" is assumed.
        `parent` - the parent component, or null if you want it to be a root component. If parent is null, the page is assumed to be the current page, which is determined by the execution context. In other words, the new component will be the root component of the current page if parent is null.
        `arg` - a map of parameters that is accessible by the arg variable in EL, or by `Execution.getArg()`. Ignored if null.
      Returns:
        the first component being created.
      Throws:
        `java.io.IOException`
      See Also:
        `createComponents(PageDefinition, Component, Map)`, `createComponents(String, Component, Map)`, `createComponentsDirectly(Document, String, Component, Map)`, `createComponentsDirectly(String, String, Component, Map)`

    - #### createComponentsDirectly

          public static Component[] createComponentsDirectly​(WebApp wapp,
                                                             java.lang.String content,
                                                             java.lang.String extension,
                                                             java.util.Map<?,​?> arg)

      Creates components that don't belong to any page from the raw content specified by a string.

      The raw content is parsed to a page definition by use of `getPageDefinitionDirectly(WebApp,String,String)`, and then invokes `createComponents(WebApp,PageDefinition,Map)` to create components.

      Unlike `createComponentsDirectly(String,String,Component,Map)`, this method can be invoked without the current execution, such as a working thread. In this case, the wapp argument must be specified.

      Parameters:
        `wapp` - the Web application. It is optional and used only if no current execution (e.g., in a working thread). The instance of `WebApp` can be retrieved by use of `WebManager.getWebApp()`, while the instance of `WebManager` can be retrieved by `WebManager.getWebManager(javax.servlet.ServletContext)`
        `content` - the raw content of the page. It must be in ZUML.
        `extension` - the default extension if the content doesn't specify an language. In other words, if the content doesn't specify an language, `LanguageDefinition.getByExtension(java.lang.String)` is called. If extension is null and the content doesn't specify a language, the language called "xul/html" is assumed.
        `arg` - a map of parameters that is accessible by the arg variable in EL, or by `Execution.getArg()`. Ignored if null.
      Returns:
        all top-level components being created.
      Since:
        3.6.2
      See Also:
        `createComponents(WebApp, PageDefinition, Map)`, `createComponents(WebApp, String, Map)`, `createComponentsDirectly(WebApp, Document, String, Map)`, `createComponentsDirectly(WebApp, Reader, String, Map)`

    - #### createComponentsDirectly

          public static Component[] createComponentsDirectly​(WebApp wapp,
                                                             Document content,
                                                             java.lang.String extension,
                                                             java.util.Map<?,​?> arg)

      Creates components that don't belong to any page from the raw content specified by a DOM tree.

      The raw content is parsed to a page definition by use of `getPageDefinitionDirectly(WebApp,Document, String)`, and then invokes `createComponents(WebApp,PageDefinition,Map)` to create components.

      Unlike `createComponentsDirectly(Document,String,Component,Map)`, this method can be invoked without the current execution, such as a working thread. In this case, the wapp argument must be specified.

      Parameters:
        `wapp` - the Web application. It is optional and used only if no current execution (e.g., in a working thread). The instance of `WebApp` can be retrieved by use of `WebManager.getWebApp()`, while the instance of `WebManager` can be retrieved by `WebManager.getWebManager(javax.servlet.ServletContext)`
        `content` - the raw content in DOM.
        `extension` - the default extension if the content doesn't specify an language. In other words, if the content doesn't specify an language, `LanguageDefinition.getByExtension(java.lang.String)` is called. If extension is null and the content doesn't specify a language, the language called "xul/html" is assumed.
        `arg` - a map of parameters that is accessible by the arg variable in EL, or by `Execution.getArg()`. Ignored if null.
      Returns:
        all top-level components being created.
      Since:
        3.6.2
      See Also:
        `createComponents(WebApp, PageDefinition, Map)`, `createComponents(WebApp, String, Map)`, `createComponentsDirectly(WebApp, Document, String, Map)`, `createComponentsDirectly(WebApp, Reader, String, Map)`

    - #### createComponentsDirectly

          public static Component[] createComponentsDirectly​(WebApp wapp,
                                                             java.io.Reader reader,
                                                             java.lang.String extension,
                                                             java.util.Map<?,​?> arg)
                                                      throws java.io.IOException

      Creates components that don't belong to any page from the raw content read from the specified reader.

      Unl

      The raw content is loaded and parsed to a page definition by use of `getPageDefinitionDirectly(WebApp,Reader,String)`, and then invokes `createComponents(WebApp,PageDefinition,Map)` to create components.

      Unlike `createComponentsDirectly(Reader,String,Component,Map)`, this method can be invoked without the current execution, such as a working thread. In this case, the wapp argument must be specified.

      Parameters:
        `wapp` - the Web application. It is optional and used only if no current execution (e.g., in a working thread). The instance of `WebApp` can be retrieved by use of `WebManager.getWebApp()`, while the instance of `WebManager` can be retrieved by `WebManager.getWebManager(javax.servlet.ServletContext)`
        `reader` - the reader to retrieve the raw content in ZUML.
        `extension` - the default extension if the content doesn't specify an language. In other words, if the content doesn't specify an language, `LanguageDefinition.getByExtension(java.lang.String)` is called. If extension is null and the content doesn't specify a language, the language called "xul/html" is assumed.
        `arg` - a map of parameters that is accessible by the arg variable in EL, or by `Execution.getArg()`. Ignored if null.
      Returns:
        all top-level components being created.
      Throws:
        `java.io.IOException`
      Since:
        3.6.2
      See Also:
        `createComponents(WebApp, PageDefinition, Map)`, `createComponents(WebApp, String, Map)`, `createComponentsDirectly(WebApp, Document, String, Map)`, `createComponentsDirectly(WebApp, String, String, Map)`

    - #### getPageDefinition

          public static PageDefinition getPageDefinition​(WebApp wapp,
                                                         java.lang.String uri)

      Returns the page definition from the page file specified by an URI.

      Like `createComponents(WebApp,PageDefinition,Map)`, this method can be invoked without the current execution, such as a working thread. In this case, the wapp argument must be specified.

      Parameters:
        `wapp` - the Web application. It is optional and used only if no current execution (e.g., in a working thread). The instance of `WebApp` can be retrieved by use of `WebManager.getWebApp()`, while the instance of `WebManager` can be retrieved by `WebManager.getWebManager(javax.servlet.ServletContext)`
        `uri` - the URI of the page file.
      Since:
        3.6.2
      See Also:
        `getPageDefinitionDirectly(WebApp, String, String)`, `getPageDefinitionDirectly(WebApp, Document, String)`, `getPageDefinitionDirectly(WebApp, Reader, String)`

    - #### getPageDefinitionDirectly

          public PageDefinition getPageDefinitionDirectly​(WebApp wapp,
                                                          java.lang.String content,
                                                          java.lang.String extension)

      Converts the specified page content to a page definition.

      Like `createComponents(WebApp,PageDefinition,Map)`, this method can be invoked without the current execution, such as a working thread. In this case, the wapp argument must be specified.

      Parameters:
        `wapp` - the Web application. It is optional and used only if no current execution (e.g., in a working thread). The instance of `WebApp` can be retrieved by use of `WebManager.getWebApp()`, while the instance of `WebManager` can be retrieved by `WebManager.getWebManager(javax.servlet.ServletContext)`
        `content` - the raw content of the page. It must be in ZUML.
        `extension` - the default extension if the content doesn't specify an language. In other words, if the content doesn't specify an language, `LanguageDefinition.getByExtension(java.lang.String)` is called. If extension is null and the content doesn't specify a language, the language called "xul/html" is assumed.
      Since:
        3.6.2
      See Also:
        `getPageDefinitionDirectly(WebApp, Document, String)`, `getPageDefinitionDirectly(WebApp, Reader, String)`, `getPageDefinition(org.zkoss.zk.ui.WebApp, java.lang.String)`

    - #### getPageDefinitionDirectly

          public PageDefinition getPageDefinitionDirectly​(WebApp wapp,
                                                          Document content,
                                                          java.lang.String extension)

      Converts the specified page content, in DOM, to a page definition.

      Like `createComponentsDirectly(WebApp,Document,String,Map)`, this method can be invoked without the current execution, such as a working thread. In this case, the wapp argument must be specified.

      Parameters:
        `wapp` - the Web application. It is optional and used only if no current execution (e.g., in a working thread). The instance of `WebApp` can be retrieved by use of `WebManager.getWebApp()`, while the instance of `WebManager` can be retrieved by `WebManager.getWebManager(javax.servlet.ServletContext)`
        `content` - the raw content of the page in DOM.
        `extension` - the default extension if the content doesn't specify an language. In other words, if the content doesn't specify an language, `LanguageDefinition.getByExtension(java.lang.String)` is called. If extension is null and the content doesn't specify a language, the language called "xul/html" is assumed.
      Since:
        3.6.2
      See Also:
        `getPageDefinitionDirectly(WebApp, String, String)`, `getPageDefinitionDirectly(WebApp, Reader, String)`, `getPageDefinition(org.zkoss.zk.ui.WebApp, java.lang.String)`

    - #### getPageDefinitionDirectly

          public PageDefinition getPageDefinitionDirectly​(WebApp wapp,
                                                          java.io.Reader reader,
                                                          java.lang.String extension)
                                                   throws java.io.IOException

      Reads the raw content from a reader and converts it into a page definition.

      Like `createComponentsDirectly(WebApp,Reader,String,Map)`, this method can be invoked without the current execution, such as a working thread. In this case, the wapp argument must be specified.

      Parameters:
        `wapp` - the Web application. It is optional and used only if no current execution (e.g., in a working thread). The instance of `WebApp` can be retrieved by use of `WebManager.getWebApp()`, while the instance of `WebManager` can be retrieved by `WebManager.getWebManager(javax.servlet.ServletContext)`
        `reader` - used to input the raw content of the page. It must be in ZUML.
        `extension` - the default extension if the content doesn't specify an language. In other words, if the content doesn't specify an language, `LanguageDefinition.getByExtension(java.lang.String)` is called. If extension is null and the content doesn't specify a language, the language called "xul/html" is assumed.
      Throws:
        `java.io.IOException`
      Since:
        3.6.2
      See Also:
        `getPageDefinitionDirectly(WebApp, String, String)`, `getPageDefinitionDirectly(WebApp, Document, String)`, `getPageDefinition(org.zkoss.zk.ui.WebApp, java.lang.String)`

    - #### sendRedirect

          public static void sendRedirect​(java.lang.String uri)

      Sends a temporary redirect response to the client using the specified redirect location URL by use of the current execution, `getCurrent()`.

      After calling this method, the caller shall end the processing immediately (by returning). All pending requests and events will be dropped.

      Parameters:
        `uri` - the URI to redirect to, or null to reload the same page
      See Also:
        `Execution.sendRedirect(java.lang.String)`

    - #### include

          public static void include​(java.lang.String page)
                              throws java.io.IOException

      A shortcut of Executions.getCurrent().include(page).
      Throws:
        `java.io.IOException`
      See Also:
        `Execution.include(java.io.Writer,String,Map,int)`, `Execution.include(String)`

    - #### forward

          public static void forward​(java.lang.String page)
                              throws java.io.IOException

      A shortcut of Executions.getCurrent().forward(page).
      Throws:
        `java.io.IOException`
      See Also:
        `Execution.forward(java.io.Writer,String,Map,int)`, `Execution.forward(String)`

    - #### wait

          public static final void wait​(java.lang.Object mutex)
                                 throws java.lang.InterruptedException,
                                        SuspendNotAllowedException

      Suspends the current processing of an event and wait until the other thread invokes `notify(Object)`, `notifyAll(Object)`, `notify(Desktop, Object)` or `notifyAll(Desktop, Object)` for the specified object.

      It can only be called when the current thread is processing an event. And, when called, the current processing is suspended and ZK continues to process the next event and finally render the result.

      It is typical use to implement a modal dialog where it won't return until the modal dialog ends.

      Parameters:
        `mutex` - any non-null object to identify what to notify. It must be same object passed to `notify(Desktop, Object)`. If there is racing issue, you have to enclose it with `synchronized` (though it is optional).
      Throws:
        `UiException` - if it is called not during event processing.
        `SuspendNotAllowedException` - if there are too many suspended exceptions. Deployers can control the maximal allowed number of suspended exceptions by specifying `max-suspended-thread` in `zk.xml`, or invoking `Configuration.setMaxSuspendedThreads(int)`.
        `java.lang.InterruptedException`

    - #### notify

          public static final void notify​(java.lang.Object mutex)

      Wakes up a single event processing thread that is waiting on the specified object.

      Unlike `notify(Desktop, Object)`, this method can be invoked only in the event listener that processing the same desktop. In addition, this method can be called under the event listener.

      Use `notify(Desktop, Object)` if you want to notify in other thread, such as a working thread.

      Parameters:
        `mutex` - any non-null object to identify what to notify. It must be same object passed to `wait(java.lang.Object)`. If there is racing issue, you have to enclose it with `synchronized` (though it is optional).
      Throws:
        `UiException` - if it is called not during event processing.
      See Also:
        `notify(Desktop, Object)`, `notifyAll(Object)`

    - #### notify

          public static final void notify​(Desktop desktop,
                                          java.lang.Object mutex)

      Wakes up a single event processing thread for the specified desktop that is waiting on the specified object.

      Unlike `notify(Object)`, this method can be called any time. It is designed to let working threads resume an event processing thread.

      Notice: if this method is NOT called in an event processing thread, the resumed thread won't execute until the next request is received. To enforce it happen, you might use the timer component (found in ZUL).

      Notice: to resolve racing issue, you usually need to follow this pattern.

                  //Event Handling Thread
                  synchronized (mutex) {
                  final WorkingThread worker = new WorkingThread(desktop);
                  synchronized (mutex) {
                          worker.start();
                          Executions.wait(mutex);
                  }
                  ....
                  }
                  //Working Thread
                  public void run() {
                  ....
                  synchronized (mutex) {
                          Executions.notify(desktop, mutex);
                  }
                  }

      Parameters:
        `desktop` - the desktop which the suspended thread is processing. It must be the same desktop of the suspended thread.
        `mutex` - any non-null object to identify what to notify. It must be same object passed to `wait(java.lang.Object)`. If there is racing issue, you have to enclose it with `synchronized` (though it is optional).
      See Also:
        `notify(Object)`, `notifyAll(Desktop, Object)`

    - #### notifyAll

          public static final void notifyAll​(java.lang.Object mutex)

      Wakes up all event processing thread that are waiting on the specified object.

      Unlike `notify(Desktop, Object)`, this method can be invoked only in the event listener that processing the same desktop. In addition, this method can be called under the event listener.

      Use `notifyAll(Desktop, Object)` if you want to notify in other thread, such as a working thread.

      Parameters:
        `mutex` - any non-null object to identify what to notify. It must be same object passed to `wait(java.lang.Object)`. If there is racing issue, you have to enclose it with `synchronized` (though it is optional).
      Throws:
        `UiException` - if it is called not during event processing.
      See Also:
        `notify(Desktop, Object)`, `notifyAll(Object)`

    - #### notifyAll

          public static final void notifyAll​(Desktop desktop,
                                             java.lang.Object mutex)

      Wakes up all event processing threads for the specified desktop that are waiting on the specified object.

      Unlike `notifyAll(Object)`, this method can be called any time. It is designed to let working threads resume an event processing thread.

      Notice: if this method is NOT called in an event processing thread, the resumed thread won't execute until the next request is received. To enforce it happen, you might use the timer component (found in ZUL).

      Notice: to resolve racing issue, you usually need to follow this pattern.

                  //Event Handling Thread
                  synchronized (mutex) {
                  final WorkingThread worker = new WorkingThread(desktop);
                  synchronized (mutex) {
                          worker.start();
                          Executions.wait(mutex);
                  }
                  ....
                  }
                  //Working Thread
                  public void run() {
                  ....
                  synchronized (mutex) {
                          Executions.notifyAll(desktop, mutex);
                  }
                  }

      Parameters:
        `desktop` - the desktop which the suspended thread is processing. It must be the same desktop of the suspended thread.
        `mutex` - any non-null object to identify what to notify. It must be same object passed to `wait(java.lang.Object)`. If there is racing issue, you have to enclose it with `synchronized` (though it is optional).
      See Also:
        `notify(Object)`, `notifyAll(Desktop, Object)`

    - #### schedule

          public static <T extends Event> void schedule​(Desktop desktop,
                                                        EventListener<T> task,
                                                        T event)

      Schedules a task to run under the server push of the given desktop asynchronously. The caller can be any thread, not limited to the event listener of the given desktop.

      The task is executed when the server push of the given desktop is granted. The task is executed asynchronously. That is, this method return without waiting for the task to be executed.

      The task is executed in the thread serving the server-push request, so no additional thread will be created. It is safe to use in a clustering environment.

      The task is represented by an event listener. When the server push is ready to serve the given task, `EventListener.onEvent(T)` is called with the given event.

      Like `activate(org.zkoss.zk.ui.Desktop)`, this method can be called anywhere, not limited to the event listener of the given desktop. It can be called even if there is no current execution.

      Alternative to `schedule(org.zkoss.zk.ui.Desktop, org.zkoss.zk.ui.event.EventListener<T>, T)`, you could use `activate(org.zkoss.zk.ui.Desktop)`/`deactivate(org.zkoss.zk.ui.Desktop)` if you prefer something to be done synchronously.

      The server-push is disabled by default. To use it, you have to enable it first with `Desktop.enableServerPush(boolean)` for the given desktop. Once enabled, you can use as many as server-push threads you like (for the desktop with the server-push feature enabled).

      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.
      Throws:
        `java.lang.IllegalStateException` - if the server push is not enabled.
        `DesktopUnavailableException` - if the desktop is removed (when activating).
      Since:
        5.0.6

    - #### activate

          public static final void activate​(Desktop desktop)
                                     throws java.lang.InterruptedException,
                                            DesktopUnavailableException

      Activates a thread to allow it access the given desktop synchronously. It causes the current thread to wait until the desktop is available to access, the desktop no longer exists, or some other thread interrupts this thread.

      Alternative to `activate(org.zkoss.zk.ui.Desktop)`/`deactivate(org.zkoss.zk.ui.Desktop)`, you could use `schedule(org.zkoss.zk.ui.Desktop, org.zkoss.zk.ui.event.EventListener<T>, T)` to execute a task under server push. `schedule(org.zkoss.zk.ui.Desktop, org.zkoss.zk.ui.event.EventListener<T>, T)` is asynchronous, while `activate(org.zkoss.zk.ui.Desktop)`/`deactivate(org.zkoss.zk.ui.Desktop)` is synchronous

      Like `schedule(org.zkoss.zk.ui.Desktop, org.zkoss.zk.ui.event.EventListener<T>, T)`, this method can be called anywhere, not limited to the event listener of the given desktop. It can be called even if there is no current execution.

      The server-push is disabled by default. To use it, you have to enable it first with `Desktop.enableServerPush(boolean)` for the given desktop. Once enabled, you can use as many as server-push threads you like (for the desktop with the server-push feature enabled).

      Before a thread, not running in the event listener of the given desktop, can access the desktop, you have to activate it first by `activate(org.zkoss.zk.ui.Desktop)`. Once this method returns, the thread is activated and it, like an event listener of the given desktop, can manipulate the desktop directly.

      A typical use pattern:

          class MyWorkingThread extends Thread {
            public void run() {
              while (anything_to_publish) {
                 //prepare something to publish
                 //you can create new components and manipulate them before
                 //activation, as long as they are not attached to the desktop

                 Executions.activate(desktop);
                 try {
                   try {
                     //activated
                     //manipulate the components that are attached the desktop
                   } finally {
                     Executions.deactivate(desktop)
                   }
                 } catch (DesktopUnavailableException ex) {
                   //clean up (since desktop is dead)
                 }
             }
           }
          }

      Note: the access of components is sequentialized. That is, at most one thread is activated. All others, including the event listeners, have to wait until it is deactivated (i.e., until `deactivate(org.zkoss.zk.ui.Desktop)` is called). Thus, it is better to minimize the time remaining activated. A typical practice is to create new components and manipulate them before activated. Then, you have to only attach them after activated.

           Tree tree = new Tree();
           new Treechildren().setParent(tree); //initialize the tree
           Exections.activate(desktop);
           try {
             tree.setPage(page); //assume page is a page of desktop

      Note: you don't need to invoke this method in the event listener since it is already activated when an event listen starts execution.

      Note: When you call this method, ZK framework would require a lock on the thread. In the rare case that the framework, at the same time, is waiting on the release of another lock from your application, then a deadlock would result.

      Throws:
        `java.lang.InterruptedException` - if it is interrupted by other thread
        `java.lang.IllegalStateException` - if the server push is not enabled.
        `DesktopUnavailableException` - if the desktop is removed (when activating).
      Since:
        3.0.0

    - #### activate

          public static final boolean activate​(Desktop desktop,
                                               long timeout)
                                        throws java.lang.InterruptedException,
                                               DesktopUnavailableException

      Activates a thread to allow it access the given desktop synchronously, or until a certain amount of time has elapsed. 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.

      Note: When you call this method, ZK framework would require a lock on the thread. In the rare case that the framework, at the same time, is waiting on the release of another lock from your application, then a deadlock would result.

      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).
        `java.lang.IllegalStateException` - if the server push is not enabled for this desktop yet (`Desktop.enableServerPush(boolean)`).
      Since:
        3.0.0
      See Also:
        `activate(Desktop)`, `deactivate(org.zkoss.zk.ui.Desktop)`

    - #### deactivate

          public static final void deactivate​(Desktop desktop)

      Deactivates a thread that has invoked `activate(org.zkoss.zk.ui.Desktop)` successfully.
      Since:
        3.0.0
      See Also:
        `activate(Desktop)`, `activate(Desktop, long)`