Package org.zkoss.zk.ui

## Interface Execution

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

      public interface Execution
      extends Scope

  An execution of a client request (e.g., ServletRequest). When a request sent from a client, the server constructs a `Execution` object to hold execution relevant info, and then serves the request thru this execution.

  A client request, e.g., HttpServletRequest, might consist of multiple ZK request (`AuRequest`). However, these ZK requests must target the same desktop of pages (`Page`).

  Because a request might come from HTTP or other protocol, Execution also serves as an isolation layer.

  Author:
    tomyeh
  See Also:
    `Page`

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `APPEND_PARAM` | Whether to append params if both uri and params contain the same parameter.
    `static int` | `IGNORE_PARAM` | Whether to ignore params if both uri and params contain the same parameter.
    `static int` | `OVERWRITE_URI` | Whether to overwrite uri if both uri and params contain the same parameter.
    `static int` | `PASS_THRU_ATTR` | Whether the specified parameters shall be passed thru the request's attribute called arg.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addAuResponse​(java.lang.String key, AuResponse resposne)` | Adds an asynchronous response (`AuResponse`) with the given key instead of `AuResponse.getOverrideKey()`.
    `void` | `addAuResponse​(AuResponse resposne)` | Adds an asynchronous response (`AuResponse`) which will be sent to client at the end of the execution.
    `void` | `addResponseHeader​(java.lang.String name, java.lang.String value)` | Adds a response header with the give name and value.
    `void` | `addResponseHeader​(java.lang.String name, java.util.Date value)` | Adds a response header with the given name and date-value.
    `boolean` | `addVariableResolver​(VariableResolver resolver)` | Adds a name resolver that will be used to resolve a variable (by `getVariableResolver()`).
    `boolean` | `containsResponseHeader​(java.lang.String name)` | Returns whether the named response header has already been set.
    `Component[]` | `createComponents​(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.
    `Component` | `createComponents​(java.lang.String uri, Component parent, java.util.Map<?,​?> arg)` | Creates components from a page file specified by an URI.
    `Component` | `createComponents​(java.lang.String uri, Component parent, Component insertBefore, VariableResolver resolver)` | Creates components from a page file specified by an URI with a custom variable resolver and inserts before a particular component.
    `Component[]` | `createComponents​(java.lang.String uri, Component parent, Component insertBefore, VariableResolver resolver, java.util.Map<?,​?> arg)` | Creates components from a page file specified by an URI with a custom variable resolver and inserts before a particular component.
    `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.
    `Component[]` | `createComponents​(PageDefinition pagedef, java.util.Map<?,​?> arg)` | Creates components that don't belong to any page from the specified page definition.
    `Component` | `createComponents​(PageDefinition pagedef, Component parent, java.util.Map<?,​?> arg)` | Creates components from the specified page definition.
    `Component` | `createComponents​(PageDefinition pagedef, Component parent, Component insertBefore, VariableResolver resolver)` | Creates components from the specified page definition with a custom variable resolver and inserts before a particular component.
    `Component[]` | `createComponentsDirectly​(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.
    `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.
    `Component` | `createComponentsDirectly​(java.io.Reader reader, java.lang.String extension, Component parent, Component insertBefore, VariableResolver resolver)` | Creates components from the raw content read from the specified reader with a custom variable resolver and inserts before a particular component.
    `Component[]` | `createComponentsDirectly​(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.
    `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.
    `Component` | `createComponentsDirectly​(java.lang.String content, java.lang.String extension, Component parent, Component insertBefore, VariableResolver resolver)` | Creates components from the raw content specified by a string with a custom variable resolver and inserts before a particular component.
    `Component[]` | `createComponentsDirectly​(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.
    `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.
    `Component` | `createComponentsDirectly​(Document content, java.lang.String extension, Component parent, Component insertBefore, VariableResolver resolver)` | Creates components from the raw content specified by a DOM tree with a custom variable resolver and inserts before a particular component.
    `java.lang.String` | `encodeURL​(java.lang.String uri)` | Encodes an URL.
    `java.lang.Object` | `evaluate​(Component comp, java.lang.String expr, java.lang.Class<?> expectedType)` | Evaluates the specified expression with ${link #getVariableResolver} and `Page.getFunctionMapper()` of the page of the specified component.
    `java.lang.Object` | `evaluate​(Page page, java.lang.String expr, java.lang.Class<?> expectedType)` | Evaluates the specified expression with ${link #getVariableResolver} and `Page.getFunctionMapper()` of the specified page.
    `void` | `forward​(java.io.Writer writer, java.lang.String page, java.util.Map<java.lang.String,​?> params, int mode)` | Forwards to another page.
    `void` | `forward​(java.lang.String page)` | A shortcut of forward(null, page, null, 0).
    `java.util.Map<?,​?>` | `getArg()` | Returns the parameters (aka., arg) if `pushArg(java.util.Map<?, ?>)` is called recently, or an empty map if not available.
    `java.lang.Object` | `getAttribute​(java.lang.String name)` | Returns the value of the specified request attribute.
    `java.util.Map<java.lang.String,​java.lang.Object>` | `getAttributes()` | Returns a map of request attributes associated with this session.
    `java.lang.String` | `getBrowser()` | Returns the name of the browser, or null if not identifiable.
    `java.lang.Double` | `getBrowser​(java.lang.String name)` | Returns the version of the given browser name, or null if the client is not the given browsers.
    `java.lang.String` | `getContextPath()` | Returns the portion of the request URI that indicates the context of the current execution.
    `default java.lang.String` | `getContextURI()` | Returns the context uri from the current execution.
    `Desktop` | `getDesktop()` | Returns the desktop associated with this execution.
    `Evaluator` | `getEvaluator​(Component comp, java.lang.Class<? extends ExpressionFactory> expfcls)` | Returns the evaluator of the current execution.
    `Evaluator` | `getEvaluator​(Page page, java.lang.Class<? extends ExpressionFactory> expfcls)` | Returns the evaluator (never null).
    `java.lang.String` | `getHeader​(java.lang.String name)` | Returns the value of the specified header as a `String`, or null if not found.
    `java.lang.Iterable<java.lang.String>` | `getHeaderNames()` | Returns all header names this request contains.
    `java.lang.Iterable<java.lang.String>` | `getHeaders​(java.lang.String name)` | Returns all the values of the specified header as an iterable `String` objects.
    `java.lang.String` | `getLocalAddr()` | Returns the Internet Protocol (IP) address of the interface on which the request was received.
    `java.lang.String` | `getLocalName()` | Returns the host name of the Internet Protocol (IP) interface on which the request was received.
    `int` | `getLocalPort()` | Returns the Internet Protocol (IP) port number of the interface on which the request was received.
    `java.lang.Object` | `getNativeRequest()` | Returns the native request, or null if not available.
    `java.lang.Object` | `getNativeResponse()` | Returns the native response, or null if not available.
    `PageDefinition` | `getPageDefinition​(java.lang.String uri)` | Returns the page definition from the page file specified by an URI.
    `PageDefinition` | `getPageDefinitionDirectly​(java.io.Reader reader, java.lang.String extension)` | Reads the raw content from a reader and converts it into a page definition.
    `PageDefinition` | `getPageDefinitionDirectly​(java.lang.String content, java.lang.String extension)` | Converts the specified page content to a page definition.
    `PageDefinition` | `getPageDefinitionDirectly​(Document content, java.lang.String extension)` | Converts the specified page content, in DOM, to a page definition.
    `java.lang.String` | `getParameter​(java.lang.String name)` | Returns the value of a request parameter as a String, or null if the parameter does not exist
    `java.util.Map<java.lang.String,​java.lang.String[]>` | `getParameterMap()` | Returns a Map of the parameters of this request.
    `java.lang.String[]` | `getParameterValues​(java.lang.String name)` | Returns an array of String objects containing all of the values the given request parameter has, or null if the parameter does not exist.
    `java.lang.String` | `getRemoteAddr()` | Returns the Internet Protocol (IP) address of the client or last proxy that sent the request.
    `java.lang.String` | `getRemoteHost()` | Returns the fully qualified name of the client or the last proxy that sent the request.
    `java.lang.String` | `getRemoteUser()` | Returns the login of the user making this request, if the user has been authenticated, or null if the user has not been authenticated.
    `java.lang.String` | `getScheme()` | Returns the name of the scheme used to make this request, for example, http, https, or ftp.
    `java.lang.String` | `getServerName()` | Returns the host name of the server to which the request was sent.
    `int` | `getServerPort()` | Returns the port number to which the request was sent.
    `Session` | `getSession()` | Returns the session this execution belongs to.
    `java.lang.String` | `getUserAgent()` | Returns the user-agent header, which indicates what the client is, or an empty string if not available.
    `java.security.Principal` | `getUserPrincipal()` | Returns a java.security.Principal object containing the name of the current authenticated user.
    `VariableResolver` | `getVariableResolver()` | Returns the variable resolver for this execution, or null if not available.
    `boolean` | `hasVariableResolver​(java.lang.Class<? extends VariableResolver> cls)` | Returns if any instance of the give class has been registered.
    `boolean` | `hasVariableResolver​(VariableResolver resolver)` | Returns if the specified variable resolved has been registered
    `void` | `include​(java.io.Writer writer, java.lang.String page, java.util.Map<java.lang.String,​?> params, int mode)` | Includes a page.
    `void` | `include​(java.lang.String page)` | A shortcut of include(null, page, null, 0).
    `boolean` | `isAsyncUpdate​(Page page)` | Returns whether this execution is an asynchronous update for the specified page (thru ZK Update Engine).
    `boolean` | `isForwarded()` | Returns whether the execution is forwarded from other pages.
    `boolean` | `isIncluded()` | Returns whether this execution is included by some other pages.
    `boolean` | `isUserInRole​(java.lang.String role)` | Returns a boolean indicating whether the authenticated user is included in the specified logical "role".
    `boolean` | `isVoided()` | Returns whether the execution is voided.
    `java.lang.String` | `locate​(java.lang.String path)` | Locates a page based on the current Locale.
    `void` | `log​(java.lang.String msg)` | Writes the specified message to a servlet log file, usually an event log.
    `void` | `log​(java.lang.String msg, java.lang.Throwable ex)` | Writes an explanatory message and a stack trace for a given Throwable exception to the servlet log file.
    `void` | `popArg()` | Pops the parameters (aka., arg) that is pushed by `pushArg(java.util.Map<?, ?>)`.
    `void` | `postEvent​(int priority, Component realTarget, Event evt)` | Queues the give event for the specified target to this execution.
    `void` | `postEvent​(int priority, Event evt)` | Queues an event with the specified priority to this execution.
    `void` | `postEvent​(Event evt)` | Queues an event to this execution.
    `void` | `pushArg​(java.util.Map<?,​?> arg)` | Pushes the parameters (aka., arg) that EL could refer it by the arg variable.
    `java.lang.Object` | `removeAttribute​(java.lang.String name)` | Removes the specified request attribute.
    `boolean` | `removeVariableResolver​(VariableResolver resolver)` | Removes a name resolve that was added by `addVariableResolver(org.zkoss.xel.VariableResolver)`.
    `void` | `sendRedirect​(java.lang.String uri)` | Sends a temporary redirect response to the client using the specified redirect location URL.
    `void` | `sendRedirect​(java.lang.String uri, boolean respRedirect)` | Send a redirect to the given url in the application the redirect is done via status 302 by `AuRedirect` if respRedirect is set to true.
    `void` | `sendRedirect​(java.lang.String uri, java.lang.String target)` | Sends a temporary redirect response to the client using the specified redirect location URL and redirect to the specified browser window.
    `java.lang.Object` | `setAttribute​(java.lang.String name, java.lang.Object value)` | Sets the value of the specified request attribute.
    `void` | `setResponseHeader​(java.lang.String name, java.lang.String value)` | Sets a response header with the give name and value.
    `void` | `setResponseHeader​(java.lang.String name, java.util.Date value)` | Sets a response header with the given name and date-value.
    `void` | `setVoided​(boolean voided)` | Sets whether the execution is voided.
    `java.lang.String` | `toAbsoluteURI​(java.lang.String uri, boolean skipInclude)` | Converts the specified URI to an absolute URI, if uri is related and the current execution is not included (`isIncluded()`).

    - ### Methods inherited from interface org.zkoss.zk.ui.ext.Scope

      `addScopeListener, getAttribute, hasAttribute, hasAttribute, removeAttribute, removeScopeListener, setAttribute`

- - ### Field Detail

    - #### OVERWRITE_URI

          static final int OVERWRITE_URI

      Whether to overwrite uri if both uri and params contain the same parameter.
      See Also:
        Constant Field Values

    - #### IGNORE_PARAM

          static final int IGNORE_PARAM

      Whether to ignore params if both uri and params contain the same parameter.
      See Also:
        Constant Field Values

    - #### APPEND_PARAM

          static final int APPEND_PARAM

      Whether to append params if both uri and params contain the same parameter. In other words, they both appear as the final query string.
      See Also:
        Constant Field Values

    - #### PASS_THRU_ATTR

          static final int PASS_THRU_ATTR

      Whether the specified parameters shall be passed thru the request's attribute called arg.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getDesktop

          Desktop getDesktop()

      Returns the desktop associated with this execution. Each execution is against exactly one desktop.

    - #### getSession

          Session getSession()

      Returns the session this execution belongs to.
      Since:
        5.0.0

    - #### isAsyncUpdate

          boolean isAsyncUpdate​(Page page)

      Returns whether this execution is an asynchronous update for the specified page (thru ZK Update Engine).
      Returns:
        whether the specified page is being asynchronous updated by this execution. If the specified page is null, this method returns whether this execution is caused by an asynchronous update (i.e., caused by an AU request).

    - #### getParameterValues

          java.lang.String[] getParameterValues​(java.lang.String name)

      Returns an array of String objects containing all of the values the given request parameter has, or null if the parameter does not exist.

    - #### getParameter

          java.lang.String getParameter​(java.lang.String name)

      Returns the value of a request parameter as a String, or null if the parameter does not exist

    - #### getParameterMap

          java.util.Map<java.lang.String,​java.lang.String[]> getParameterMap()

      Returns a Map of the parameters of this request. Request parameters are extra information sent with the request.

    - #### getEvaluator

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

      Returns the evaluator (never null). 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

          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

          java.lang.Object evaluate​(Component comp,
                                    java.lang.String expr,
                                    java.lang.Class<?> expectedType)

      Evaluates the specified expression with ${link #getVariableResolver} and `Page.getFunctionMapper()` of the page of the specified component.

      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` - used as the self variable and to retrieve the function mapper. Ignored if null.
      See Also:
        `getVariableResolver()`, `getEvaluator(org.zkoss.zk.ui.Page, java.lang.Class<? extends org.zkoss.xel.ExpressionFactory>)`

    - #### evaluate

          java.lang.Object evaluate​(Page page,
                                    java.lang.String expr,
                                    java.lang.Class<?> expectedType)

      Evaluates the specified expression with ${link #getVariableResolver} and `Page.getFunctionMapper()` of the specified page.

      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:
        `page` - used as the self variable and to retrieve the function mapper. Ignored if null.
      See Also:
        `getVariableResolver()`, `getEvaluator(org.zkoss.zk.ui.Page, java.lang.Class<? extends org.zkoss.xel.ExpressionFactory>)`

    - #### getVariableResolver

          VariableResolver getVariableResolver()

      Returns the variable resolver for this execution, or null if not available.

      Note: the resolver is similar to PageContext's if this execution is caused by a HTTP request.

      See Also:
        `evaluate(Component,String,Class)`

    - #### addVariableResolver

          boolean addVariableResolver​(VariableResolver resolver)

      Adds a name resolver that will be used to resolve a variable (by `getVariableResolver()`).

      The new added variable resolver is called first, so it has the higher priority than the previous added variable resolver. In additions, the priority of the variable resolver added with this method is higher than the variable resolvers added to a page (`Page.addVariableResolver(org.zkoss.xel.VariableResolver)`). However, its priority is lower than attributes defined in the execution and components.

      Notice that `getVariableResolver()` returns a variable resolver used to evaluate EL expressions. It resolves all builtin names and all custom variable resolvers. It is not any variable resolver added by this method.

      Returns:
        whether the resolver is added successfully. Note: if the resolver was added before, it won't be added again and this method returns false.
      Since:
        6.0.0

    - #### removeVariableResolver

          boolean removeVariableResolver​(VariableResolver resolver)

      Removes a name resolve that was added by `addVariableResolver(org.zkoss.xel.VariableResolver)`.
      Returns:
        false if resolved is not added before.
      Since:
        6.0.0

    - #### hasVariableResolver

          boolean hasVariableResolver​(VariableResolver resolver)

      Returns if the specified variable resolved has been registered
      Since:
        6.0.0
      See Also:
        `addVariableResolver(org.zkoss.xel.VariableResolver)`

    - #### hasVariableResolver

          boolean hasVariableResolver​(java.lang.Class<? extends VariableResolver> cls)

      Returns if any instance of the give class has been registered.
      Since:
        6.0.1

    - #### postEvent

          void postEvent​(Event evt)

      Queues an event to this execution. In other words, the event is placed to the event queue.

      The priority of the event is assumed to be 0. Refer to `postEvent(int, Event)` for more information.

      See Also:
        `postEvent(int, Event)`, `postEvent(int, Component, Event)`

    - #### postEvent

          void postEvent​(int priority,
                         Event evt)

      Queues an event with the specified priority to this execution. In other words, the event is placed to the event queue with the specified priority.

      The event will be sent to the component specified in `Event.getTarget()`. If `Event.getTarget()` is null, it means broadcast, i.e., all root components will receive this event. If you prefer a different target, you could use `postEvent(int, Component, Event)` instead.

      The posted events are processed from the higher priority to the lower one. If two events are posted with the same priority, the earlier the event being posted is processed earlier (first-in-first-out).

      The priority posted by posted by `postEvent(Event)` is 0. Applications shall not use the priority higher than 10,000 and lower than -10,000 since they are reserved for component development.

      Parameters:
        `priority` - the priority of the event. The default priority is 0 and the higher value means higher priority.
      Since:
        3.0.7
      See Also:
        `postEvent(int, Component, Event)`

    - #### postEvent

          void postEvent​(int priority,
                         Component realTarget,
                         Event evt)

      Queues the give event for the specified target to this execution. The target could be different from `Event.getTarget()`.
      Parameters:
        `priority` - the priority of the event. The default priority is 0 and the higher value means higher priority.
        `realTarget` - the target component that will receive the event. If null, it means broadcast, i.e., all root components will receive this event.
        Notice that postEvent(n, event) is the same as postEvent(n, event.getTarget(), event), but different from postEvent(n, 0, event).
      Since:
        5.0.7

    - #### include

          void include​(java.io.Writer writer,
                       java.lang.String page,
                       java.util.Map<java.lang.String,​?> params,
                       int mode)
                throws java.io.IOException

      Includes a page.
      Parameters:
        `writer` - the output to write. If null, the response's default writer is used.
        `page` - the page's uri; null to denote the same request
        `mode` - one of `OVERWRITE_URI`, `IGNORE_PARAM`, `APPEND_PARAM` and `PASS_THRU_ATTR`. It defines how to handle if both uri and params contains the same parameter. mode is used only if both uri contains query string and params is not empty.
      Throws:
        `java.io.IOException`

    - #### include

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

      A shortcut of include(null, page, null, 0).
      Throws:
        `java.io.IOException`

    - #### forward

          void forward​(java.io.Writer writer,
                       java.lang.String page,
                       java.util.Map<java.lang.String,​?> params,
                       int mode)
                throws java.io.IOException

      Forwards to another page.

      Note: this method can be called only when loading a page. Use `sendRedirect(String)` instead if you want to change to another desktop when processing a request from the client.

      Parameters:
        `writer` - the output to write. If null, the response's default writer is used.
        `page` - the page's uri; null to denote the same request
        `mode` - one of `OVERWRITE_URI`, `IGNORE_PARAM`, `APPEND_PARAM` and `PASS_THRU_ATTR`. It defines how to handle if both uri and params contains the same parameter. mode is used only if both uri contains query string and params is not empty.
      Throws:
        `java.io.IOException`

    - #### forward

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

      A shortcut of forward(null, page, null, 0).
      Throws:
        `java.io.IOException`

    - #### locate

          java.lang.String locate​(java.lang.String path)

      Locates a page based on the current Locale. It never returns null.

      If an URI contains "*", it will be replaced with a proper Locale. For example, if the current Locale is zh_TW and the resource is named "ab*.cd", then it searches "ab_zh_TW.cd", "ab_zh.cd" and then "ab.cd", until any of them is found.

      > Note: "*" must be right before ".", or the last character. For example, "ab*.cd" and "ab*" are both correct, while "ab*cd" and "ab*\/cd" are ignored.

      If an URI contains two "*", the first "*" will be replaced with a browser code and the second with a proper locale. The browser code depends on what browser the user are used to visit the web site. Currently, the code for Internet Explorer is "ie", Safari is "saf", Opera is "opr" and all others are "moz". Thus, in the above example, if the resource is named "ab**.cd" and Firefox is used, then it searches "abmoz_zh_TW.cd", "abmoz_zh.cd" and then "abmoz.cd", until any of them is found.

      Note: it assumes the path as name_lang_cn_var.ext where ".ext" is optional. Example, my_zh_tw.html.jsp.

      If an URI starting with "~./", it assumes the resource is from the class path.

      Parameters:
        `path` - the page path excluding servlet name. It is OK to have the query string. It might contain "*" for current browser code and Locale.
      Returns:
        the path that matches the wildcard; `path`, otherwise
      Since:
        3.6.3

    - #### isVoided

          boolean isVoided()

      Returns whether the execution is voided. By void we mean ZK Loader shall stop evaluation of a ZUML document, since the request will be taken charged by other servlet or redirect to another page. The execution shall not do anything more. In other words, the execution is avoided and won't generate any output.

      The common cause of being voided is the invocation of `forward(java.io.Writer, java.lang.String, java.util.Map<java.lang.String, ?>, int)`.

      Since:
        2.4.0

    - #### setVoided

          void setVoided​(boolean voided)

      Sets whether the execution is voided. By void we mean ZK Loader shall stop evaluation of a ZUML document, since the request will be taken charged by other servlet or redirect to another page.

      If you invoke `forward(java.io.Writer, java.lang.String, java.util.Map<java.lang.String, ?>, int)`, this method is called automatically with true. Thus, you rarely need to invoke this method, unless you forward to other servlet by use javax.servlet.RequestDispatcher directly.

      The other case to invoke this method is if you'd like to redirect to another (by specifying the refresh header).

      If the ZK page has already been created, this method throws an IllegalStateException, i.e. you cannot invoke this method in `Composer.doAfterCompose(Component)`. (@since 6.5.5)

      Since:
        2.4.1

    - #### isIncluded

          boolean isIncluded()

      Returns whether this execution is included by some other pages.

    - #### isForwarded

          boolean isForwarded()

      Returns whether the execution is forwarded from other pages.
      Since:
        2.4.0

    - #### toAbsoluteURI

          java.lang.String toAbsoluteURI​(java.lang.String uri,
                                         boolean skipInclude)

      Converts the specified URI to an absolute URI, if uri is related and the current execution is not included (`isIncluded()`).

      Note: an asynchronous update is processed by the update servlet. It is different from the servlet for rendering the ZUML page. In other words, a relative URI won't be interpreted correctly, so you have to invoke this method to convert them if necessary.

      In additions, RequestDispatcher.include doesn't handle related URI well.

      Parameters:
        `skipInclude` - whether not to convert to an absolute URI if the current page is included by another page. If you are not sure, you might specify false.

    - #### encodeURL

          java.lang.String encodeURL​(java.lang.String uri)

      Encodes an URL.

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

    - #### getUserPrincipal

          java.security.Principal getUserPrincipal()

      Returns a java.security.Principal object containing the name of the current authenticated user. If the user has not been authenticated, the method returns null.

    - #### isUserInRole

          boolean isUserInRole​(java.lang.String role)

      Returns a boolean indicating whether the authenticated user is included in the specified logical "role". Roles and role membership can be defined using deployment descriptors. If the user has not been authenticated, the method returns false.
      Parameters:
        `role` - a String specifying the name of the role

    - #### getRemoteUser

          java.lang.String getRemoteUser()

      Returns the login of the user making this request, if the user has been authenticated, or null if the user has not been authenticated. Whether the user name is sent with each subsequent request depends on the browser and type of authentication.

    - #### getRemoteHost

          java.lang.String getRemoteHost()

      Returns the fully qualified name of the client or the last proxy that sent the request. If the engine cannot or chooses not to resolve the hostname (to improve performance), this method returns the dotted-string form of the IP address.

    - #### getRemoteAddr

          java.lang.String getRemoteAddr()

      Returns the Internet Protocol (IP) address of the client or last proxy that sent the request.

    - #### getServerName

          java.lang.String getServerName()

      Returns the host name of the server to which the request was sent. It is the value of the part before ":" in the Host header value, if any, or the resolved server name, or the server IP address.
      See Also:
        `getLocalName()`

    - #### getServerPort

          int getServerPort()

      Returns the port number to which the request was sent. It is the value of the part after ":" in the Host header value, if any, or the server port where the client connection was accepted on.
      See Also:
        `getLocalPort()`

    - #### getLocalName

          java.lang.String getLocalName()

      Returns the host name of the Internet Protocol (IP) interface on which the request was received.

      Note: it is the host name defined in the server. To retrieve the name in URL, use `getServerName()`.

      See Also:
        `getServerName()`

    - #### getLocalAddr

          java.lang.String getLocalAddr()

      Returns the Internet Protocol (IP) address of the interface on which the request was received.

    - #### getLocalPort

          int getLocalPort()

      Returns the Internet Protocol (IP) port number of the interface on which the request was received.
      See Also:
        `getServerPort()`

    - #### getScheme

          java.lang.String getScheme()

      Returns the name of the scheme used to make this request, for example, http, https, or ftp. Different schemes have different rules for constructing URLs, as noted in RFC 1738.
      Since:
        3.5.0

    - #### getContextPath

          java.lang.String getContextPath()

      Returns the portion of the request URI that indicates the context of the current execution. The path starts with a "/" character but does not end with a "/" character. For servlets in the default (root) context, this method returns "".

      If the client is not using HTTP to access, this method return "";

      See Also:
        `Page.getRequestPath()`

    - #### getPageDefinition

          PageDefinition getPageDefinition​(java.lang.String uri)

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

      Implementation Notes: this method must invoke `UiFactory.getPageDefinition(org.zkoss.zk.ui.sys.RequestInfo, String)`

      Parameters:
        `uri` - the URI of the page file.
      See Also:
        `getPageDefinitionDirectly(String, String)`, `getPageDefinitionDirectly(Document, String)`, `getPageDefinitionDirectly(Reader, String)`

    - #### getPageDefinitionDirectly

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

      Converts the specified page content to a page definition.

      Implementation Notes: this method must invoke `UiFactory.getPageDefinitionDirectly(org.zkoss.zk.ui.sys.RequestInfo, String, String)`

      Parameters:
        `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.
      See Also:
        `getPageDefinitionDirectly(Document, String)`, `getPageDefinitionDirectly(Reader, String)`, `getPageDefinition(java.lang.String)`

    - #### getPageDefinitionDirectly

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

      Converts the specified page content, in DOM, to a page definition.
      Parameters:
        `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.
      See Also:
        `getPageDefinitionDirectly(String, String)`, `getPageDefinitionDirectly(Reader, String)`, `getPageDefinition(java.lang.String)`

    - #### getPageDefinitionDirectly

          PageDefinition getPageDefinitionDirectly​(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.
      Parameters:
        `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`
      See Also:
        `getPageDefinitionDirectly(String, String)`, `getPageDefinitionDirectly(Document, String)`, `getPageDefinition(java.lang.String)`

    - #### createComponents

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

      Creates components from the specified page definition. The created components become the child of the specified parent, or become the root components of the current page if parent is specified as null.
      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 `getArg()`. Ignored if null.
      Returns:
        the first component being created.
      See Also:
        `createComponents(String, Component, Map)`

    - #### createComponents

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

      Creates components from a page file specified by an URI. The created components become the child of the specified parent, or become the root components of the current page if parent is specified as null.

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

      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 `getArg()`. Ignored if null.
      See Also:
        `createComponents(PageDefinition, Component, Map)`, `createComponentsDirectly(String, String, Component, Map)`, `createComponentsDirectly(Document, String, Component, Map)`, `createComponentsDirectly(Reader, String, Component, Map)`

    - #### createComponents

          Component createComponents​(PageDefinition pagedef,
                                     Component parent,
                                     Component insertBefore,
                                     VariableResolver resolver)

      Creates components from the specified page definition with a custom variable resolver and inserts before a particular component. The created components become the child of the specified parent, or become the root components of the current page if parent is specified as null.
      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.
        `insertBefore` - the sibling component that new components will be inserted before. Ignored if null (i.e., append as last children).
        `resolver` - the variable resolver used to resolve variables. Ignored if null.
      Returns:
        the first component being created.
      Since:
        6.0.0
      See Also:
        `createComponents(String, Component, Component, VariableResolver)`

    - #### createComponents

          Component createComponents​(java.lang.String uri,
                                     Component parent,
                                     Component insertBefore,
                                     VariableResolver resolver)

      Creates components from a page file specified by an URI with a custom variable resolver and inserts before a particular component. The created components become the child of the specified parent, or become the root components of the current page if parent is specified as null.

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

      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.
        `insertBefore` - the sibling component that new components will be inserted before. Ignored if null (i.e., append as last children).
        `resolver` - the variable resolver used to resolve variables. Ignored if null.
      Since:
        6.0.0
      See Also:
        `createComponents(PageDefinition, Component, Component, VariableResolver)`, `createComponentsDirectly(String, String, Component, Component, VariableResolver)`, `createComponentsDirectly(Document, String, Component, Component, VariableResolver)`, `createComponentsDirectly(Reader, String, Component, Component, VariableResolver)`

    - #### createComponents

          Component[] createComponents​(java.lang.String uri,
                                       Component parent,
                                       Component insertBefore,
                                       VariableResolver resolver,
                                       java.util.Map<?,​?> arg)

      Creates components from a page file specified by an URI with a custom variable resolver and inserts before a particular component. The created components become the child of the specified parent, or become the root components of the current page if parent is specified as null.

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

      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.
        `insertBefore` - the sibling component that new components will be inserted before. Ignored if null (i.e., append as last children).
        `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 `getArg()`. Ignored if null.
      Since:
        8.0.0
      See Also:
        `createComponents(PageDefinition, Component, Component, VariableResolver)`, `createComponentsDirectly(String, String, Component, Component, VariableResolver)`, `createComponentsDirectly(Document, String, Component, Component, VariableResolver)`, `createComponentsDirectly(Reader, String, Component, Component, VariableResolver)`

    - #### createComponents

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

      Creates components that don't belong to any page from the specified page definition.
      Parameters:
        `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 `getArg()`. Ignored if null.
      Returns:
        the first component being created.
      Since:
        2.4.0
      See Also:
        `createComponents(String, Map)`

    - #### createComponents

          Component[] createComponents​(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(java.lang.String)` ), and then invokes `createComponents(PageDefinition,Map)` to create components.

      Parameters:
        `arg` - a map of parameters that is accessible by the arg variable in EL, or by `getArg()`. Ignored if null.
      Since:
        2.4.0
      See Also:
        `createComponents(PageDefinition, Map)`, `createComponentsDirectly(String, String, Map)`, `createComponentsDirectly(Document, String, Map)`, `createComponentsDirectly(Reader, String, Map)`

    - #### createComponents

          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.

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

      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 `getArg()`. Ignored if null.
      Since:
        8.0.1
      See Also:
        `createComponents(PageDefinition, Map)`, `createComponentsDirectly(String, String, Map)`, `createComponentsDirectly(Document, String, Map)`, `createComponentsDirectly(Reader, String, Map)`

    - #### createComponentsDirectly

          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. The created components become the child of the specified parent, or become the root components of the current page if parent is specified as null.

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

      Parameters:
        `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.
        `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 `getArg()`. Ignored if null.
      See Also:
        `createComponents(PageDefinition, Component, Map)`, `createComponents(String, Component, Map)`, `createComponentsDirectly(Document, String, Component, Map)`, `createComponentsDirectly(Reader, String, Component, Map)`

    - #### createComponentsDirectly

          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. The created components become the child of the specified parent, or become the root components of the current page if parent is specified as null.

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

      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 `getArg()`. Ignored if null.
      See Also:
        `createComponents(PageDefinition, Component, Map)`, `createComponents(String, Component, Map)`, `createComponentsDirectly(Document, String, Component, Map)`, `createComponentsDirectly(Reader, String, Component, Map)`

    - #### createComponentsDirectly

          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. The created components become the child of the specified parent, or become the root components of the current page if parent is specified as null.

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

      Parameters:
        `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.
        `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 `getArg()`. Ignored if null.
      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

          Component createComponentsDirectly​(java.lang.String content,
                                             java.lang.String extension,
                                             Component parent,
                                             Component insertBefore,
                                             VariableResolver resolver)

      Creates components from the raw content specified by a string with a custom variable resolver and inserts before a particular component. The created components become the child of the specified parent, or become the root components of the current page if parent is specified as null.

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

      Parameters:
        `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.
        `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.
        `insertBefore` - the sibling component that new components will be inserted before. Ignored if null (i.e., append as last children).
        `resolver` - the variable resolver used to resolve variables.
      Since:
        6.0.0
      See Also:
        `createComponents(PageDefinition, Component, Component, VariableResolver)`, `createComponents(String, Component, Component, VariableResolver)`, `createComponentsDirectly(Document, String, Component, Component, VariableResolver)`, `createComponentsDirectly(Reader, String, Component, Component, VariableResolver)`

    - #### createComponentsDirectly

          Component createComponentsDirectly​(Document content,
                                             java.lang.String extension,
                                             Component parent,
                                             Component insertBefore,
                                             VariableResolver resolver)

      Creates components from the raw content specified by a DOM tree with a custom variable resolver and inserts before a particular component. The created components become the child of the specified parent, or become the root components of the current page if parent is specified as null.

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

      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.
        `insertBefore` - the sibling component that new components will be inserted before. Ignored if null (i.e., append as last children).
        `resolver` - the variable resolver used to resolve variables. Ignored if null.
      Since:
        6.0.0
      See Also:
        `createComponents(PageDefinition, Component, Component, VariableResolver)`, `createComponents(String, Component, Component, VariableResolver)`, `createComponentsDirectly(Document, String, Component, Component, VariableResolver)`, `createComponentsDirectly(Reader, String, Component, Component, VariableResolver)`

    - #### createComponentsDirectly

          Component createComponentsDirectly​(java.io.Reader reader,
                                             java.lang.String extension,
                                             Component parent,
                                             Component insertBefore,
                                             VariableResolver resolver)
                                      throws java.io.IOException

      Creates components from the raw content read from the specified reader with a custom variable resolver and inserts before a particular component. The created components become the child of the specified parent, or become the root components of the current page if parent is specified as null.

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

      Parameters:
        `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.
        `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.
        `insertBefore` - the sibling component that new components will be inserted before. Ignored if null (i.e., append as last children).
        `resolver` - the variable resolver used to resolve variables. Ignored if null.
      Throws:
        `java.io.IOException`
      Since:
        6.0.0
      See Also:
        `createComponents(PageDefinition, Component, Component, VariableResolver)`, `createComponents(String, Component, Component, VariableResolver)`, `createComponentsDirectly(Document, String, Component, Component, VariableResolver)`, `createComponentsDirectly(String, String, Component, Component, VariableResolver)`

    - #### createComponentsDirectly

          Component[] createComponentsDirectly​(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(String, String)`, and then invokes `createComponents(PageDefinition,Map)` to create components.

      Parameters:
        `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 `getArg()`. Ignored if null.
      Since:
        2.4.0
      See Also:
        `createComponents(PageDefinition, Map)`, `createComponents(String, Map)`, `createComponentsDirectly(Document, String, Map)`, `createComponentsDirectly(Reader, String, Map)`

    - #### createComponentsDirectly

          Component[] createComponentsDirectly​(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(Document, String)`, and then invokes `createComponents(PageDefinition,Map)` to create components.

      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.
        `arg` - a map of parameters that is accessible by the arg variable in EL, or by `getArg()`. Ignored if null.
      Since:
        2.4.0
      See Also:
        `createComponents(PageDefinition, Map)`, `createComponents(String, Map)`, `createComponentsDirectly(Document, String, Map)`, `createComponentsDirectly(Reader, String, Map)`

    - #### createComponentsDirectly

          Component[] createComponentsDirectly​(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.

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

      Parameters:
        `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 `getArg()`. Ignored if null.
      Throws:
        `java.io.IOException`
      Since:
        2.4.0
      See Also:
        `createComponents(PageDefinition, Map)`, `createComponents(String, Map)`, `createComponentsDirectly(Document, String, Map)`, `createComponentsDirectly(String, String, Map)`

    - #### sendRedirect

          void sendRedirect​(java.lang.String uri)

      Sends a temporary redirect response to the client using the specified redirect location URL.

      It is the same as sendRedirect(url, null).

      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

    - #### sendRedirect

          void sendRedirect​(java.lang.String uri,
                            java.lang.String target)

      Sends a temporary redirect response to the client using the specified redirect location URL and redirect to the specified browser window.

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

      Note: if you specify target other than null and "_self", it'll fail if the browser prevent the server to popup a window.

      Parameters:
        `uri` - the URI to redirect to, or null to reload the same page
        `target` - the name of the browser window that send-redirect will load the specified URI, or null if the current browser window is used.

    - #### sendRedirect

          void sendRedirect​(java.lang.String uri,
                            boolean respRedirect)

      Send a redirect to the given url in the application the redirect is done via status 302 by `AuRedirect` if respRedirect is set to true. If respRedirect is set to false, it is the same with `sendRedirect(String)`.
      Parameters:
        `uri` - the URI to redirect to, or null to reload the same page
        `respRedirect` - whether to send redirect by HttpResponse or not
      Since:
        7.0.0

    - #### getArg

          java.util.Map<?,​?> getArg()

      Returns the parameters (aka., arg) if `pushArg(java.util.Map<?, ?>)` is called recently, or an empty map if not available.

      The use of parameters is application dependent. ZK only provides the way to store (`pushArg(java.util.Map<?, ?>)` and to restore `popArg()`. And, let the parameters being accessible in EL by referring it as the arg variable.

      Currently, `createComponents(String,Component,Map)` and similar methods use this mechanism to let caller customize a page definition.

      Notice that `createComponents(String,Component,Map)` pops arg after creating components, and before processing any event. In other words, it is not aviable for event listener, including onCreate. However, `CreateEvent.getArg()` preserves the map for its event listeners.

    - #### pushArg

          void pushArg​(java.util.Map<?,​?> arg)

      Pushes the parameters (aka., arg) that EL could refer it by the arg variable. Remember to call `popArg()` in the finally clause.
      See Also:
        `getArg()`

    - #### popArg

          void popArg()

      Pops the parameters (aka., arg) that is pushed by `pushArg(java.util.Map<?, ?>)`.

      It never throws an exception.

      See Also:
        `getArg()`

    - #### addAuResponse

          void addAuResponse​(AuResponse resposne)

      Adds an asynchronous response (`AuResponse`) which will be sent to client at the end of the execution. It is the same as `addAuResponse(response.getOverrideKey(), resposne)`

      If `AuResponse.getDepends()` is not null, the response depends on the returned componet. In other words, the response is removed if the component is removed. If it is null, the response is component-independent.

      Since:
        5.0.2

    - #### addAuResponse

          void addAuResponse​(java.lang.String key,
                             AuResponse resposne)

      Adds an asynchronous response (`AuResponse`) with the given key instead of `AuResponse.getOverrideKey()`.

      If `AuResponse.getDepends()` is not null, the response depends on the returned componet. In other words, the response is removed if the component is removed. If it is null, the response is component-independent.

      Parameters:
        `key` - could be anything. If not null, the second invocation of this method in the same execution with the same key and the same depends (`AuResponse.getDepends()`) will override the previous one. In other words, the previous one will be dropped. If null is specified, the response is simply appended to the end without overriding any previous one.

    - #### getBrowser

          java.lang.Double getBrowser​(java.lang.String name)

      Returns the version of the given browser name, or null if the client is not the given browsers.

      Notice that, after this method is called, an attribute named zk will be stored to the request, such that you can retrieve the browser information by use of EL, such as `${zk.ie > 7}`.

      Parameters:
        `name` - the browser's name. It includes "ie", "ff", "gecko", "webkit", "safari" and "opera". And, "ff" is the same as "gecko", and "webit" is the same as "safari".
      Since:
        6.0.0

    - #### getBrowser

          java.lang.String getBrowser()

      Returns the name of the browser, or null if not identifiable.
      Since:
        6.0.0

    - #### getUserAgent

          java.lang.String getUserAgent()

      Returns the user-agent header, which indicates what the client is, or an empty string if not available.

      Note: it doesn't return null, so it is easy to test what the client is with `String.indexOf(int)`.

      Since:
        3.0.2

    - #### getNativeRequest

          java.lang.Object getNativeRequest()

      Returns the native request, or null if not available.

      The returned object depends on the Web container. If it is based Java servlet container, an instance of javax.servlet.ServletRequest is returned.

    - #### getNativeResponse

          java.lang.Object getNativeResponse()

      Returns the native response, or null if not available.

      The returned object depends on the Web container. If it is based Java servlet container, an instance of javax.servlet.ServletResponse is returned.

    - #### getAttribute

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

      Returns the value of the specified request attribute.
      Specified by:
        `getAttribute` in interface `Scope`

    - #### setAttribute

          java.lang.Object setAttribute​(java.lang.String name,
                                        java.lang.Object value)

      Sets the value of the specified request attribute.
      Specified by:
        `setAttribute` in interface `Scope`
      Parameters:
        `value` - the value. If null, the attribute is removed.
      Returns:
        the previous value if any (since ZK5)

    - #### removeAttribute

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

      Removes the specified request attribute.
      Specified by:
        `removeAttribute` in interface `Scope`
      Returns:
        the previous value if any (since ZK5)

    - #### getAttributes

          java.util.Map<java.lang.String,​java.lang.Object> getAttributes()

      Returns a map of request attributes associated with this session.
      Specified by:
        `getAttributes` in interface `Scope`

    - #### getHeader

          java.lang.String getHeader​(java.lang.String name)

      Returns the value of the specified header as a `String`, or null if not found.
      Since:
        3.5.0

    - #### getHeaders

          java.lang.Iterable<java.lang.String> getHeaders​(java.lang.String name)

      Returns all the values of the specified header as an iterable `String` objects.

      If the request did not include any headers of the specified name, this method returns an empty iterable. If the container does not allow access to header information, it returns null.

      Since:
        6.0.0

    - #### getHeaderNames

          java.lang.Iterable<java.lang.String> getHeaderNames()

      Returns all header names this request contains. If the request has no headers, this method returns an empty iterable. If the container does not allow access to header information, it returns null.
      Since:
        6.0.0

    - #### setResponseHeader

          void setResponseHeader​(java.lang.String name,
                                 java.lang.String value)

      Sets a response header with the give name and value. If the header had already been set, the new value overwrites the previous one.
      Parameters:
        `value` - the additional header value If it contains octet string, it should be encoded according to RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt).
      Since:
        3.5.0
      See Also:
        `containsResponseHeader(java.lang.String)`

    - #### setResponseHeader

          void setResponseHeader​(java.lang.String name,
                                 java.util.Date value)

      Sets a response header with the given name and date-value.
      Since:
        5.0.2

    - #### addResponseHeader

          void addResponseHeader​(java.lang.String name,
                                 java.lang.String value)

      Adds a response header with the give name and value. This method allows response headers to have multiple values.
      Parameters:
        `value` - the additional header value If it contains octet string, it should be encoded according to RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt).
      Since:
        3.5.0

    - #### addResponseHeader

          void addResponseHeader​(java.lang.String name,
                                 java.util.Date value)

      Adds a response header with the given name and date-value.
      Since:
        5.0.2

    - #### containsResponseHeader

          boolean containsResponseHeader​(java.lang.String name)

      Returns whether the named response header has already been set.
      Since:
        3.5.0

    - #### log

          void log​(java.lang.String msg)

      Writes the specified message to a servlet log file, usually an event log. The name and type of the servlet log file is specific to the servlet container.
      Since:
        6.0.0

    - #### log

          void log​(java.lang.String msg,
                   java.lang.Throwable ex)

      Writes an explanatory message and a stack trace for a given Throwable exception to the servlet log file. The name and type of the servlet log file is specific to the servlet container, usually an event log.
      Since:
        6.0.0

    - #### getContextURI

          default java.lang.String getContextURI()

      Returns the context uri from the current execution.
      Since:
        9.6.0