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

Modifier and Type	Method	Description
PageDefinition	getPageDefinition(RequestInfo ri, String path)	Returns the page definition of the specified path, or null if not found.
PageDefinition	getPageDefinitionDirectly(RequestInfo ri, Reader reader, String extension)	Returns the page definition of the specified reader; never null.
PageDefinition	getPageDefinitionDirectly(RequestInfo ri, String content, String extension)	Returns the page definition of the specified content; never null.
PageDefinition	getPageDefinitionDirectly(RequestInfo ri, org.zkoss.idom.Document content, String extension)	Returns the page definition of the specified content; never null.
Richlet	getRichlet(RequestInfo ri, 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, 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, Class klass)	Creates and initializes a composer of the given class and page.
Composer	newComposer(Page page, String className)	Creates and initializes a composer of the given class name and page.
Desktop	newDesktop(RequestInfo ri, String updateURI, String path)	Creates an instance of Desktop.
default Desktop	newDesktop(RequestInfo ri, String updateURI, String resourceURI, String path)	Creates an instance of Desktop.
Page	newPage(RequestInfo ri, PageDefinition pagedef, String path)	Creates an instance of Page for the specified page definition.
Page	newPage(RequestInfo ri, Richlet richlet, String path)	Creates an instance of Page for the specified richlet.
ServerPush	newServerPush(Desktop desktop, Class klass)	Creates and initializes the server push of the given class and desktop.
Session	newSession(WebApp wapp, Object nativeSess, Object request)	Creates an instance of Session.
void	start(WebApp wapp)	Starts this factory.
void	stop(WebApp wapp)	Stops this factory.

Method Details

start

void start(WebApp wapp)

Starts this factory.

stop

void stop(WebApp wapp)

Stops this factory.

newSession

Session newSession(WebApp wapp,
 Object nativeSess,
 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 jakarta.servlet.http.HttpSession.

request - the original request. If HTTP, it is jakarta.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,
 String path)

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

newDesktop

Desktop newDesktop(RequestInfo ri,
 String updateURI,
 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,
 String updateURI,
 String resourceURI,
 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,
 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,
 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,
 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,
 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,
 String className)
              throws 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

ClassNotFoundException

Since:

6.0.0

newServerPush

ServerPush newServerPush(Desktop desktop,
 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,
 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,
 String content,
 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,
 org.zkoss.idom.Document content,
 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,
 Reader reader,
 String extension)
                                  throws 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:

IOException

See Also:

• getPageDefinition(org.zkoss.zk.ui.sys.RequestInfo, java.lang.String)