Package org.zkoss.zk.ui.sys

## Interface UiFactory

- All Known Implementing Classes:
    `AbstractUiFactory`, `SerializableUiFactory`, `SimpleUiFactory`

      public interface UiFactory

  Used to create `Session`, `Desktop`, `Page`, `Component`, `Composer`, and `ServerPush`. It is also used to load path/URL into `PageDefinition`.

  To customize the implementation of `WebApp`, please specify web-app-class or web-app-factory-class instead (of implementing this interface).

  Rather than implementing this interface from scratch, you could extend from `SimpleUiFactory` (for non-clustering environment) or `SerializableUiFactory` (for clustering environment).

  Author:
    tomyeh
  See Also:
    `WebAppFactory`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `PageDefinition` | `getPageDefinition​(RequestInfo ri, java.lang.String path)` | Returns the page definition of the specified path, or null if not found.
    `PageDefinition` | `getPageDefinitionDirectly​(RequestInfo ri, java.io.Reader reader, java.lang.String extension)` | Returns the page definition of the specified reader; never null.
    `PageDefinition` | `getPageDefinitionDirectly​(RequestInfo ri, java.lang.String content, java.lang.String extension)` | Returns the page definition of the specified content; never null.
    `PageDefinition` | `getPageDefinitionDirectly​(RequestInfo ri, Document content, java.lang.String extension)` | Returns the page definition of the specified content; never null.
    `Richlet` | `getRichlet​(RequestInfo ri, java.lang.String path)` | Returns a richlet for specified request, or null if the richlet is not found..
    `boolean` | `isRichlet​(RequestInfo ri, boolean bRichlet)` | Tests whether the specified request is a richlet.
    `Component` | `newComponent​(Page page, Component parent, ComponentDefinition compdef, java.lang.String clsnm)` | Creates and initializes a component based on the specified `ComponentDefinition`.
    `Component` | `newComponent​(Page page, Component parent, ComponentInfo compInfo, Component insertBefore)` | Creates and initializes a component based on the specified `ComponentInfo`.
    `Component` | `newComponent​(Page page, Component parent, ShadowInfo compInfo, Component insertBefore)` | Creates and initializes a shadow based on the specified `ShadowInfo`.
    `Composer` | `newComposer​(Page page, java.lang.Class klass)` | Creates and initializes a composer of the given class and page.
    `Composer` | `newComposer​(Page page, java.lang.String className)` | Creates and initializes a composer of the given class name and page.
    `Desktop` | `newDesktop​(RequestInfo ri, java.lang.String updateURI, java.lang.String path)` | Creates an instance of `Desktop`.
    `default Desktop` | `newDesktop​(RequestInfo ri, java.lang.String updateURI, java.lang.String resourceURI, java.lang.String path)` | Creates an instance of `Desktop`.
    `Page` | `newPage​(RequestInfo ri, PageDefinition pagedef, java.lang.String path)` | Creates an instance of `Page` for the specified page definition.
    `Page` | `newPage​(RequestInfo ri, Richlet richlet, java.lang.String path)` | Creates an instance of `Page` for the specified richlet.
    `ServerPush` | `newServerPush​(Desktop desktop, java.lang.Class klass)` | Creates and initializes the server push of the given class and desktop.
    `Session` | `newSession​(WebApp wapp, java.lang.Object nativeSess, java.lang.Object request)` | Creates an instance of `Session`.
    `void` | `start​(WebApp wapp)` | Starts this factory.
    `void` | `stop​(WebApp wapp)` | Stops this factory.

- - ### Method Detail

    - #### start

          void start​(WebApp wapp)

      Starts this factory.

    - #### stop

          void stop​(WebApp wapp)

      Stops this factory.

    - #### newSession

          Session newSession​(WebApp wapp,
                             java.lang.Object nativeSess,
                             java.lang.Object request)

      Creates an instance of `Session`.
      Parameters:
        `wapp` - the web application
        `nativeSess` - the native session depending on the Web server. If HTTP is used, it is javax.servlet.http.HttpSession.
        `request` - the original request. If HTTP, it is javax.servlet.http.HttlServletRequest.
      Since:
        3.0.1

    - #### isRichlet

          boolean isRichlet​(RequestInfo ri,
                            boolean bRichlet)

      Tests whether the specified request is a richlet.

      If this method returns true, `getRichlet(org.zkoss.zk.ui.sys.RequestInfo, java.lang.String)` is called to create the richlet. Otherwise, `getPageDefinition(org.zkoss.zk.ui.sys.RequestInfo, java.lang.String)` is called to retrieve the page definition from a ZUML page.

      Parameters:
        `bRichlet` - the default value that this method shall return. It is a suggestion. If you don't know what to do, just return bRichlet.
      Returns:
        true if it is a richlet, or false if it is a ZUML page.

    - #### getRichlet

          Richlet getRichlet​(RequestInfo ri,
                             java.lang.String path)

      Returns a richlet for specified request, or null if the richlet is not found..

    - #### newDesktop

          Desktop newDesktop​(RequestInfo ri,
                             java.lang.String updateURI,
                             java.lang.String path)

      Creates an instance of `Desktop`.

      Note: the returned instance must also implement `DesktopCtrl`.

      Parameters:
        `ri` - the additional request information.
        `updateURI` - the URI that is used as the base to generate URI for asynchronous updates. In other words, it is used to implement `Desktop.getUpdateURI(java.lang.String)`
        `path` - the path to request this desktop, such as "/test/test.zul", or null if it is caused by a filter.

    - #### newDesktop

          default Desktop newDesktop​(RequestInfo ri,
                                     java.lang.String updateURI,
                                     java.lang.String resourceURI,
                                     java.lang.String path)

      Creates an instance of `Desktop`.

      Note: the returned instance must also implement `DesktopCtrl`.

      Parameters:
        `ri` - the additional request information.
        `updateURI` - the URI that is used as the base to generate URI for asynchronous updates. In other words, it is used to implement `Desktop.getUpdateURI(java.lang.String)`
        `resourceURI` - the URI that is used to get ZK resource
        `path` - the path to request this desktop, such as "/test/test.zul", or null if it is caused by a filter.
      Since:
        9.5.0

    - #### newPage

          Page newPage​(RequestInfo ri,
                       PageDefinition pagedef,
                       java.lang.String path)

      Creates an instance of `Page` for the specified page definition.

      Note: the returned instance must also implement `PageCtrl`.

      Parameters:
        `ri` - the additional request information.
        `pagedef` - the page definition. If null, it means the page is served by a `Richlet` instance.
        `path` - the path to request this page, or null if it is caused by a filter.

    - #### newPage

          Page newPage​(RequestInfo ri,
                       Richlet richlet,
                       java.lang.String path)

      Creates an instance of `Page` for the specified richlet.

      Note: the returned instance must also implement `PageCtrl`.

    - #### newComponent

          Component newComponent​(Page page,
                                 Component parent,
                                 ComponentInfo compInfo,
                                 Component insertBefore)

      Creates and initializes a component based on the specified `ComponentInfo`.

      After called, the new component is added to the page, and becomes a child of the specified parent, if any. In addition, the properties and custom attributes defined in `ComponentDefinition` and `ComponentInfo` are all applied to the new component.

      Parameters:
        `page` - the page that the new component belongs to (never null).
        `parent` - the parent component, or null if the new component is root.
        `compInfo` - the component information
      Since:
        6.0.0

    - #### newComponent

          Component newComponent​(Page page,
                                 Component parent,
                                 ShadowInfo compInfo,
                                 Component insertBefore)

      Creates and initializes a shadow based on the specified `ShadowInfo`.

      After called, the new shadow element is added to the host component, if any. In addition, the properties are all applied to the new shadow element.

      Parameters:
        `page` - the page that the host component belongs to (never null).
        `parent` - the parent shadow, or null if the new shadow is root.
        `compInfo` - the shadow information
      Since:
        8.0.0

    - #### newComponent

          Component newComponent​(Page page,
                                 Component parent,
                                 ComponentDefinition compdef,
                                 java.lang.String clsnm)

      Creates and initializes a component based on the specified `ComponentDefinition`.

      After called, the new component is added to the page, and becomes a child of the specified parent, if any. In addition, the properties and custom attributes defined in `ComponentDefinition` are all applied to the new component.

      Parameters:
        `page` - the page that the new component belongs to (never null).
        `parent` - the parent component, or null if the new component is root.
        `clsnm` - the implementation class of the component. If null, `ComponentDefinition.getImplementationClass()` will be used.

    - #### newComposer

          Composer newComposer​(Page page,
                               java.lang.Class klass)

      Creates and initializes a composer of the given class and page.
      Parameters:
        `page` - the page that the composer will be created for.
      Throws:
        `UiException` - if failed to instantiate
      Since:
        6.0.0

    - #### newComposer

          Composer newComposer​(Page page,
                               java.lang.String className)
                        throws java.lang.ClassNotFoundException

      Creates and initializes a composer of the given class name and page. In most cases, the implementation could use `Page.resolveClass(java.lang.String)` to resolve the class, if page is not null.
      Parameters:
        `page` - the page that the composer will be created for.
      Throws:
        `UiException` - if failed to instantiate
        `java.lang.ClassNotFoundException`
      Since:
        6.0.0

    - #### newServerPush

          ServerPush newServerPush​(Desktop desktop,
                                   java.lang.Class klass)

      Creates and initializes the server push of the given class and desktop.
      Parameters:
        `desktop` - the desktop that the server push will be created for.
      Throws:
        `UiException` - if failed to instantiate
      Since:
        6.0.0

    - #### getPageDefinition

          PageDefinition getPageDefinition​(RequestInfo ri,
                                           java.lang.String path)

      Returns the page definition of the specified path, or null if not found.

      Note: unlike `newDesktop(org.zkoss.zk.ui.sys.RequestInfo, java.lang.String, java.lang.String)` and `newPage(org.zkoss.zk.ui.sys.RequestInfo, org.zkoss.zk.ui.metainfo.PageDefinition, java.lang.String)`, it won't be called if it is created thru filter. If filter, `getPageDefinitionDirectly(org.zkoss.zk.ui.sys.RequestInfo, java.lang.String, java.lang.String)` is called.

      Typical use: retrieve the content from a database based on the specified path, and then invoke `getPageDefinitionDirectly(org.zkoss.zk.ui.sys.RequestInfo, java.lang.String, java.lang.String)` to 'convert' the content into a page definition (`PageDefinition`).

      Notice that a page definition usually contains taglib or zscript files. These files are located by `RequestInfo.getLocator()`. If you want them to be loaded from the database too, you must invoke `RequestInfo.setLocator(org.zkoss.util.resource.Locator)` to change the default locator.

      Implementation NOTE: DO NOT invoke `Execution.getPageDefinition(String)`. Otherwise, an endless loop occurs.

      Parameters:
        `ri` - the additional request information.
        `path` - the path to request this page.
      See Also:
        `getPageDefinitionDirectly(org.zkoss.zk.ui.sys.RequestInfo, java.lang.String, java.lang.String)`

    - #### getPageDefinitionDirectly

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

      Returns the page definition of the specified content; never null.

      It is called when a filter or `Execution.getPageDefinitionDirectly(String, String)` is going to generate a page definition for the content it intercepts.

      Implementation NOTE: DO NOT invoke `Execution.getPageDefinitionDirectly(String, String)`. Otherwise, an endless loop occurs.

      Parameters:
        `content` - the raw content of the page. It must be in ZUML.
        `extension` - the default extension if doc doesn't specify an language. Ignored if null. If extension is null and the content doesn't specify a language, the language called "xul/html" is assumed.
      See Also:
        `getPageDefinition(org.zkoss.zk.ui.sys.RequestInfo, java.lang.String)`

    - #### getPageDefinitionDirectly

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

      Returns the page definition of the specified content; never null.

      It is called when `Execution.getPageDefinitionDirectly(Document, String)` is going to generate a page definition for the content it intercepts.

      Implementation NOTE: DO NOT invoke `Execution.getPageDefinitionDirectly(Document, String)`. Otherwise, an endless loop occurs.

      Parameters:
        `content` - the raw content of the page in DOM.
        `extension` - the default extension if doc doesn't specify an language. Ignored if null. If extension is null and the content doesn't specify a language, the language called "xul/html" is assumed.
      See Also:
        `getPageDefinition(org.zkoss.zk.ui.sys.RequestInfo, java.lang.String)`

    - #### getPageDefinitionDirectly

          PageDefinition getPageDefinitionDirectly​(RequestInfo ri,
                                                   java.io.Reader reader,
                                                   java.lang.String extension)
                                            throws java.io.IOException

      Returns the page definition of the specified reader; never null.

      It is called when `Execution.getPageDefinitionDirectly(Reader, String)` is going to generate a page definition for the content it intercepts.

      Implementation NOTE: DO NOT invoke `Execution.getPageDefinitionDirectly(Reader, String)`. Otherwise, an endless loop occurs.

      Parameters:
        `reader` - the reader to retrieve the raw content in ZUML.
        `extension` - the default extension if doc doesn't specify an language. Ignored if null. 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:
        `getPageDefinition(org.zkoss.zk.ui.sys.RequestInfo, java.lang.String)`