Package org.zkoss.zk.ui

## Interface WebApp

- All Superinterfaces:
    `Locator`, `Scope`
  All Known Implementing Classes:
    `AbstractWebApp`, `SimpleWebApp`

      public interface WebApp
      extends Scope, Locator

  Represents a Web application. A web application is usually in form of a war file. An application might have multiple Web applications.

  In HTTP, Web application represents a servlet context that supports ZK. In other word, a Web application is created if `DHtmlLayoutServlet` is declared in web.xml.

  To get the current Web application, use `Desktop.getWebApp()`.

  Author:
    tomyeh

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.String` | `getAppName()` | Returns the application name, never null.
    `java.lang.Object` | `getAttribute​(java.lang.String name)` | Returns the value of the specified custom attribute.
    `java.util.Map<java.lang.String,​java.lang.Object>` | `getAttributes()` | Returns a map of custom attributes associated with this object.
    `java.lang.String` | `getBuild()` | Returns the build identifier, such as 2007121316.
    `Configuration` | `getConfiguration()` | Returns the configuration.
    `java.lang.String` | `getInitParameter​(java.lang.String name)` | Returns the value of the named context-wide initialization parameter, or null if the parameter does not exist.
    `java.lang.Iterable<java.lang.String>` | `getInitParameterNames()` | Returns the names of the context's initialization parameters as an iterable String objects (never null).
    `java.lang.String` | `getMimeType​(java.lang.String file)` | Returns the MIME type of the specified file, or null if the MIME type is not known.
    `java.lang.String` | `getRealPath​(java.lang.String path)` | Returns a String containing the real path for a given virtual path.
    `java.net.URL` | `getResource​(java.lang.String path)` | Returns a URL to the resource that is mapped to a specified path.
    `java.io.InputStream` | `getResourceAsStream​(java.lang.String path)` | Returns the resource located at the named path as an InputStream object.
    `java.util.Set<java.lang.String>` | `getResourcePaths​(java.lang.String path)` | Returns a directory-like listing of all the paths to resources within the web application whose longest sub-path matches the supplied path argument.
    `default java.lang.String` | `getResourceURI()` | Returns the URI for ZK resource.
    `default java.lang.String` | `getResourceURI​(boolean encode)` | Returns the URI for ZK resource that can be encoded or not.
    `javax.servlet.ServletContext` | `getServletContext()` | Returns the servlet context of this application.
    `int` | `getSubversion​(int portion)` | Returns a portion of the version in an integer by specifying its index.
    `java.lang.String` | `getUpdateURI()` | Returns the URI for asynchronous update.
    `java.lang.String` | `getUpdateURI​(boolean encode)` | Returns the URI for asynchronous update that can be encoded or not.
    `java.lang.String` | `getVersion()` | Returns the ZK version, such as "1.1.0" and "2.0.0".
    `WebApp` | `getWebApp​(java.lang.String uripath)` | Returns the WebApp that corresponds to a specified URL on the server, or null if either none exists or the container wishes to restrict this access..
    `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.
    `java.lang.Object` | `removeAttribute​(java.lang.String name)` | Removes the specified custom attribute.
    `void` | `setAppName​(java.lang.String name)` | Sets the application name.
    `java.lang.Object` | `setAttribute​(java.lang.String name, java.lang.Object value)` | Sets the value of the specified custom attribute.

    - ### Methods inherited from interface org.zkoss.util.resource.Locator

      `getDirectory`

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

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

- - ### Method Detail

    - #### getAppName

          java.lang.String getAppName()

      Returns the application name, never null. Developer can set it to any name that describes his application.

      Default: ZK

    - #### setAppName

          void setAppName​(java.lang.String name)

      Sets the application name. Developer can set it to any name that describes his application.

    - #### getVersion

          java.lang.String getVersion()

      Returns the ZK version, such as "1.1.0" and "2.0.0".
      See Also:
        `getSubversion(int)`, `Utils.parseVersion(java.lang.String)`, `Utils.compareVersion(int[], int[])`

    - #### getBuild

          java.lang.String getBuild()

      Returns the build identifier, such as 2007121316.

      Each time ZK is built, a different build identifier is assigned.

      Since:
        3.0.1

    - #### getSubversion

          int getSubversion​(int portion)

      Returns a portion of the version in an integer by specifying its index. For example, getSubversion(0) returns the so-called major version (2 in "2.4.0"), getSubversion(1) returns the so-called minor version (4 in "2.4.0"), and both getSubversion(2) and getSubversion(3) return 0.
      Parameters:
        `portion` - which portion of the version; starting from 0. If you want to retrieve the major version, specify 0.
      Since:
        3.0.0
      See Also:
        `getVersion()`

    - #### getAttribute

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

      Returns the value of the specified custom 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 custom attribute.
      Specified by:
        `setAttribute` in interface `Scope`
      Returns:
        the previous value if any (since ZK 5)

    - #### removeAttribute

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

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

    - #### getAttributes

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

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

    - #### getWebApp

          WebApp getWebApp​(java.lang.String uripath)

      Returns the WebApp that corresponds to a specified URL on the server, or null if either none exists or the container wishes to restrict this access..

    - #### getResource

          java.net.URL getResource​(java.lang.String path)

      Returns a URL to the resource that is mapped to a specified path.

      Notice that, since 3.6.3, this method can retrieve the resource starting with "~./". If the path contains the wildcard ('*'), you can use `Execution.locate(java.lang.String)` to convert it to a proper string first.

      Specified by:
        `getResource` in interface `Locator`
      Returns:
        a URL for reading the resource, or null if the resource could not be found or the caller doesn't have adequate privileges to get the resource

    - #### getResourceAsStream

          java.io.InputStream getResourceAsStream​(java.lang.String path)

      Returns the resource located at the named path as an InputStream object.

      Notice that, since 3.6.3, this method can retrieve the resource starting with "~./". If the path contains the wildcard ('*'), you can use `Execution.locate(java.lang.String)` to convert it to a proper string first.

      Specified by:
        `getResourceAsStream` in interface `Locator`
      Returns:
        an input stream for reading the resource, or null if the resource could not be found or the caller doesn't have adequate privileges to get the resource

    - #### getRealPath

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

      Returns a String containing the real path for a given virtual path. For example, the path "/index.html" returns the absolute file path on the server's filesystem would be served by a request for "http://host/contextPath/index.html", where contextPath is the context path of this `WebApp`.

      Notice that ZK don't count on this method to retrieve resources. If you want to change the mapping of URI to different resources, override `UiFactory.getPageDefinition(org.zkoss.zk.ui.sys.RequestInfo, java.lang.String)` instead.

    - #### getMimeType

          java.lang.String getMimeType​(java.lang.String file)

      Returns the MIME type of the specified file, or null if the MIME type is not known. The MIME type is determined by the configuration of the Web container.

      Common MIME types are "text/html" and "image/gif".

    - #### getResourcePaths

          java.util.Set<java.lang.String> getResourcePaths​(java.lang.String path)

      Returns a directory-like listing of all the paths to resources within the web application whose longest sub-path matches the supplied path argument. Paths indicating subdirectory paths end with a '/'. The returned paths are all relative to the root of the web application and have a leading '/'. For example, for a web application containing

                  /welcome.html
                  /catalog/index.html
                  /catalog/products.html
                  /catalog/offers/books.html
                  /catalog/offers/music.html
                  /customer/login.jsp
                  /WEB-INF/web.xml
                  /WEB-INF/classes/com.acme.OrderServlet.class,

                  getResourcePaths("/") returns {"/welcome.html", "/catalog/", "/customer/", "/WEB-INF/"}
                  getResourcePaths("/catalog/") returns {"/catalog/index.html", "/catalog/products.html", "/catalog/offers/"}.

    - #### getInitParameter

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

      Returns the value of the named context-wide initialization parameter, or null if the parameter does not exist.

    - #### getInitParameterNames

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

      Returns the names of the context's initialization parameters as an iterable String objects (never null).
      Since:
        6.0.0

    - #### getUpdateURI

          java.lang.String getUpdateURI()

      Returns the URI for asynchronous update.

      Both `getUpdateURI()` and `Desktop.getUpdateURI(java.lang.String)` are encoded with `Execution.encodeURL(java.lang.String)`

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

    - #### getUpdateURI

          java.lang.String getUpdateURI​(boolean encode)

      Returns the URI for asynchronous update that can be encoded or not.
      Parameters:
        `encode` - whether to encode with `Execution.encodeURL(java.lang.String)`. It is the same as `getUpdateURI()` if `encode` is true.
      Throws:
        `java.lang.NullPointerException` - if the current execution is not available and encode is true.
      Since:
        5.0.0

    - #### getConfiguration

          Configuration getConfiguration()

      Returns the configuration.

    - #### getServletContext

          javax.servlet.ServletContext getServletContext()

      Returns the servlet context of this application.
      Since:
        6.0.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

    - #### getResourceURI

          default java.lang.String getResourceURI()

      Returns the URI for ZK resource.

      Both `getResourceURI()` and `Desktop.getResourceURI(java.lang.String)` are encoded with `Execution.encodeURL(java.lang.String)`

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

    - #### getResourceURI

          default java.lang.String getResourceURI​(boolean encode)

      Returns the URI for ZK resource that can be encoded or not.
      Parameters:
        `encode` - whether to encode with `Execution.encodeURL(java.lang.String)`. It is the same as `getResourceURI()` if `encode` is true.
      Throws:
        `java.lang.NullPointerException` - if the current execution is not available and encode is true.
      Since:
        9.5.0