/* UiFactory.java
Purpose:
Description:
History:
Wed Apr 19 10:50:48 2006, Created by tomyeh
Copyright (C) 2006 Potix Corporation. All Rights Reserved.
{{IS_RIGHT
This program is distributed under LGPL Version 2.1 in the hope that
it will be useful, but WITHOUT ANY WARRANTY.
}}IS_RIGHT
*/
package org.zkoss.zk.ui.sys;
import java.io.IOException;
import java.io.Reader;
import org.zkoss.idom.Document;
import org.zkoss.zk.ui.Component;
import org.zkoss.zk.ui.Desktop;
import org.zkoss.zk.ui.Page;
import org.zkoss.zk.ui.Richlet;
import org.zkoss.zk.ui.Session;
import org.zkoss.zk.ui.UiException;
import org.zkoss.zk.ui.WebApp;
import org.zkoss.zk.ui.metainfo.ComponentDefinition;
import org.zkoss.zk.ui.metainfo.ComponentInfo;
import org.zkoss.zk.ui.metainfo.PageDefinition;
import org.zkoss.zk.ui.metainfo.ShadowInfo;
import org.zkoss.zk.ui.util.Composer;
/**
* Used to create {@link Session}, {@link Desktop}, {@link Page},
* {@link Component}, {@link Composer}, and {@link ServerPush}.
* It is also used to load path/URL into {@link PageDefinition}.
*
* <p>To customize the implementation of {@link WebApp}, please
* specify <a href="http://books.zkoss.org/wiki/ZK_Configuration_Reference/zk.xml/The_system-config_Element/The_web-app-class_Element">web-app-class</a>
* or <a href="http://books.zkoss.org/wiki/ZK_Configuration_Reference/zk.xml/The_system-config_Element/The_web-app-factory-class_Element">web-app-factory-class</a>
* instead (of implementing this interface).
*
* <p>Rather than implementing this interface from scratch, you could
* extend from {@link org.zkoss.zk.ui.http.SimpleUiFactory}
* (for non-clustering environment)
* or {@link org.zkoss.zk.ui.http.SerializableUiFactory}
* (for clustering environment).
*
* @author tomyeh
* @see WebAppFactory
*/
public interface UiFactory {
/** Starts this factory.
*/
public void start(WebApp wapp);
/** Stops this factory.
*/
public void stop(WebApp wapp);
/** Creates an instance of {@link Session}.
*
* @param wapp the web application
* @param nativeSess the native session depending on the Web server.
* If HTTP is used, it is javax.servlet.http.HttpSession.
* @param request the original request. If HTTP, it is
* javax.servlet.http.HttlServletRequest.
* @since 3.0.1
*/
public Session newSession(WebApp wapp, Object nativeSess, Object request);
/** Tests whether the specified request is a richlet.
*
* <p>If this method returns true, {@link #getRichlet} is called to create
* the richlet. Otherwise, {@link #getPageDefinition} is called to retrieve
* the page definition from a ZUML page.
*
* @param bRichlet the default value that this method shall return.
* It is a suggestion. If you don't know what to do, just return bRichlet.
* @return true if it is a richlet, or false if it is a ZUML page.
*/
public boolean isRichlet(RequestInfo ri, boolean bRichlet);
/** Returns a richlet for specified request, or null if the richlet is not found..
*/
public Richlet getRichlet(RequestInfo ri, String path);
/** Creates an instance of {@link Desktop}.
*
* <p>Note: the returned instance must also implement {@link DesktopCtrl}.
*
* @param ri the additional request information.
* @param updateURI the URI that is used as the base to generate
* URI for asynchronous updates. In other words, it is used to
* implement {@link Desktop#getUpdateURI}
* @param path the path to request this desktop, such as "/test/test.zul",
* or null if it is caused by a filter.
*/
public Desktop newDesktop(RequestInfo ri, String updateURI, String path);
/** Creates an instance of {@link Page} for the specified page definition.
*
* <p>Note: the returned instance must also implement {@link PageCtrl}.
*
* @param ri the additional request information.
* @param pagedef the page definition. If null, it means the page is served
* by a {@link Richlet} instance.
* @param path the path to request this page, or null if it is caused
* by a filter.
*/
public Page newPage(RequestInfo ri, PageDefinition pagedef, String path);
/** Creates an instance of {@link Page} for the specified richlet.
*
* <p>Note: the returned instance must also implement {@link PageCtrl}.
*/
public Page newPage(RequestInfo ri, Richlet richlet, String path);
/** Creates and initializes a component based on the specified
* {@link ComponentInfo}.
*
* <p>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 {@link ComponentDefinition}
* and {@link ComponentInfo} are all
* applied to the new component.
*
* @param page the page that the new component belongs to (never null).
* @param parent the parent component, or null if the new component is root.
* @param compInfo the component information
* @since 6.0.0
*/
public Component newComponent(Page page, Component parent, ComponentInfo compInfo, Component insertBefore);
/** Creates and initializes a shadow based on the specified
* {@link ShadowInfo}.
*
* <p>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.
*
* @param page the page that the host component belongs to (never null).
* @param parent the parent shadow, or null if the new shadow is root.
* @param compInfo the shadow information
* @since 8.0.0
*/
public Component newComponent(Page page, Component parent, ShadowInfo compInfo, Component insertBefore);
/** Creates and initializes a component based on the specified
* {@link ComponentDefinition}.
*
* <p>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 {@link ComponentDefinition} are all
* applied to the new component.
*
* @param page the page that the new component belongs to (never null).
* @param parent the parent component, or null if the new component is root.
* @param clsnm the implementation class of the component.
* If null, {@link ComponentDefinition#getImplementationClass} will
* be used.
*/
public Component newComponent(Page page, Component parent, ComponentDefinition compdef, String clsnm);
/** Creates and initializes a composer of the given class and page.
* @param page the page that the composer will be created for.
* @exception UiException if failed to instantiate
* @since 6.0.0
*/
public Composer newComposer(Page page, Class klass);
/** Creates and initializes a composer of the given class name and page.
* In most cases, the implementation could use {@link Page#resolveClass}
* to resolve the class, if page is not null.
* @param page the page that the composer will be created for.
* @exception UiException if failed to instantiate
* @since 6.0.0
*/
public Composer newComposer(Page page, String className) throws ClassNotFoundException;
/** Creates and initializes the server push of the given class and desktop.
* @param desktop the desktop that the server push will be created for.
* @exception UiException if failed to instantiate
* @since 6.0.0
*/
public ServerPush newServerPush(Desktop desktop, Class klass);
/** Returns the page definition of the specified path, or null if
* not found.
*
* <p>Note: unlike {@link #newDesktop} and {@link #newPage},
* it won't be called if it is created thru filter. If filter,
* {@link #getPageDefinitionDirectly} is called.
*
* <p>Typical use: retrieve the content from a database based on
* the specified path, and then invoke {@link #getPageDefinitionDirectly}
* to 'convert' the content into a page definition ({@link PageDefinition}).
*
* <p>Notice that a page definition usually contains taglib or zscript
* files. These files are located by {@link RequestInfo#getLocator}.
* If you want them
* to be loaded from the database too, you must invoke
* {@link RequestInfo#setLocator} to change the default locator.
*
* <p>Implementation NOTE: DO NOT invoke
* {@link org.zkoss.zk.ui.Execution#getPageDefinition(String)}.
* Otherwise, an endless loop occurs.
*
* @param ri the additional request information.
* @param path the path to request this page.
* @see #getPageDefinitionDirectly
*/
public PageDefinition getPageDefinition(RequestInfo ri, String path);
/** Returns the page definition of the specified content; never null.
*
* <p>It is called when a filter or {@link org.zkoss.zk.ui.Execution#getPageDefinitionDirectly(String, String)}
* is going to generate a page definition for the content it intercepts.
*
* <p>Implementation NOTE: DO NOT invoke
* {@link org.zkoss.zk.ui.Execution#getPageDefinitionDirectly(String, String)}.
* Otherwise, an endless loop occurs.
*
* @param content the raw content of the page. It must be in ZUML.
* @param 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 #getPageDefinition
*/
public PageDefinition getPageDefinitionDirectly(RequestInfo ri, String content, String extension);
/** Returns the page definition of the specified content; never null.
*
* <p>It is called when {@link org.zkoss.zk.ui.Execution#getPageDefinitionDirectly(Document, String)}
* is going to generate a page definition for the content it intercepts.
*
* <p>Implementation NOTE: DO NOT invoke
* {@link org.zkoss.zk.ui.Execution#getPageDefinitionDirectly(Document, String)}.
* Otherwise, an endless loop occurs.
*
* @param content the raw content of the page in DOM.
* @param 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 #getPageDefinition
*/
public PageDefinition getPageDefinitionDirectly(RequestInfo ri, Document content, String extension);
/** Returns the page definition of the specified reader; never null.
*
* <p>It is called when {@link org.zkoss.zk.ui.Execution#getPageDefinitionDirectly(Reader, String)}
* is going to generate a page definition for the content it intercepts.
*
* <p>Implementation NOTE: DO NOT invoke
* {@link org.zkoss.zk.ui.Execution#getPageDefinitionDirectly(Reader, String)}.
* Otherwise, an endless loop occurs.
*
* @param reader the reader to retrieve the raw content in ZUML.
* @param 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 #getPageDefinition
*/
public PageDefinition getPageDefinitionDirectly(RequestInfo ri, Reader reader, String extension) throws IOException;
}