org.zkoss.zk.ui
Interface Page

All Superinterfaces:

IdSpace

All Known Implementing Classes:

PageImpl

public interface Page
extends IdSpace

A page. A desktop consists of a set of pages.

When a ZK request is asking to render a new page, a new page is created and components that are created duing this request all belong to this page.

If a ZK requst is asking an update, it must have at lease one UUID of a component (Component.getUuid(). From this UUID, we know which page it belongs and activate it to process the update.

By activation, the system guarantees no concurrent access to pages and components (so you don't need use synchronized for them).

Desktop

In portal and some environments, a client request (e.g., ServletRequest) might consists of several ZK requests (AuRequest). While each ZK request might ask to create an independent page, all these pages are grouped as a desktop, such that they are activated and removed at the same time. Moreover, pages in the same desktop could communicate to eath other (see Inter-page communication).

A session, Session, might have multiple desktops of pages, Page, while a page belongs to exactly one session. A page, Page, might have many components, Component, while a component belongs to exactly one page.

All components of the same desktop of pages are removed at the same time if a page become 'obsolete'.

During each execution (${link Execution}), exactly one desktop of pages are locked (aka., activated). Though an execution serves a client request (e.g., ServletRequest), a client request might consist of multiple ZK request (AuRequest). Each ZK request might target to a different page (of the same desktop).

Inter-page Communication

To do inter-page communication, you could do:

1. Invoke methods of components from another page directly.
2. Use Execution.postEvent(org.zkoss.zk.ui.event.Event) to post events to components from another page.

They are the same as handling components from the same page. However, invoking method directly for components from another page has one restriction:
It cannot create component.

Author:

tomyeh

Field Summary

static int	APPLICATION_SCOPE Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the whole application.
static int	DESKTOP_SCOPE Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same desktop.
static int	PAGE_SCOPE Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same page.
static int	REQUEST_SCOPE Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same request.
static int	SESSION_SCOPE Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same session.

Method Summary

boolean	addEventListener(java.lang.String evtnm, EventListener listener) Adds an event listener to specified event for all components in this page.
void	addFunctionMapper(javax.servlet.jsp.el.FunctionMapper funmap) Adds the function mapper in addition to the current one.
boolean	addVariableResolver(VariableResolver resolver) Adds a name resolver that will be used to resolve a variable by getVariable(java.lang.String).
boolean	containsVariable(java.lang.String name) Returns whether the specified variable is defined.
java.lang.Object	getAttribute(java.lang.String name) Returns the value of the specified attribute associated with this page.
java.lang.Object	getAttribute(java.lang.String name, int scope) Returns the value of the specified custom attribute in the specified scope.
java.util.Map	getAttributes() Returns all custom attributes associated with this page.
java.util.Map	getAttributes(int scope) Returns all custom attributes of the specified scope.
ComponentDefinition	getComponentDefinition(java.lang.Class cls, boolean recur) Returns the component definition of the specified class, or null if not found.
ComponentDefinition	getComponentDefinition(java.lang.String name, boolean recur) Returns the component definition of the specified name, or null if not found.
ComponentDefinitionMap	getComponentDefinitionMap() Returns the map of component definitions (never null).
Desktop	getDesktop() Returns the desktop that this page belongs to.
java.lang.Object	getELVariable(java.lang.String name) Returns a variable that is visible to EL expressions.
javax.servlet.jsp.el.FunctionMapper	getFunctionMapper() Returns the function mapper for resolving EL functions, or null if not available.
java.lang.String	getId() Returns ID which is unique in the request (never null).
Interpreter	getInterpreter(java.lang.String zslang) Returns the interpreter of the specified scripting language.
LanguageDefinition	getLanguageDefinition() Returns the language definition that this page belongs to (never null).
java.util.Iterator	getListenerIterator(java.lang.String evtnm) Returns an iterator for iterating listener for the specified event.
java.util.Collection	getLoadedInterpreters() Returns all loaded interpreters.
Namespace	getNamespace() Returns the namespace used to store variables belonging to the ID space of this page.
java.lang.String	getRequestPath() Returns the request path of this page, or "" if not available.
java.util.Collection	getRoots() Returns a readonly list of the root components.
java.lang.String	getStyle() Returns the CSS style of this page, or empty if not specified.
java.lang.String	getTitle() Returns the title of the desktop this page belongs to (and evaluate it if it contains an expression).
java.lang.String	getUuid() Returns UUID (universal unique ID) which is unquie in the whole session.
java.lang.Object	getVariable(java.lang.String name) Returns the value of a variable defined in the namespace (getNamespace()).
java.lang.Class	getZScriptClass(java.lang.String clsnm) Returns the class of the specified name by searching the thread class loader and the classes defined in the loaded interpreters.
java.lang.String	getZScriptLanguage() Returns the default scripting language which is assumed when a zscript element doesn't specify any language.
Method	getZScriptMethod(Namespace ns, java.lang.String name, java.lang.Class[] argTypes) Returns the variable of the specified name by searching the logical scope of the specified namespace for all the loaded interpreters.
Method	getZScriptMethod(java.lang.String name, java.lang.Class[] argTypes) Returns the variable of the specified name by searching the loaded interpreters.
java.lang.Object	getZScriptVariable(Namespace ns, java.lang.String name) Returns the value of the variable of the specified name by searching the logical scope of the specified namespace for all the loaded interpreters, if any.
java.lang.Object	getZScriptVariable(java.lang.String name) Returns the value of the variable of the specified name by searching the loaded interpreters, if any.
void	interpret(java.lang.String zslang, java.lang.String script, Namespace ns) Interpret a script of the specified scripting language against the specified namespace.
void	invalidate() Invalidates this page to cause all components to redraw.
boolean	isListenerAvailable(java.lang.String evtnm) Returns whether the event listener is available.
java.lang.Object	removeAttribute(java.lang.String name) Removes the specified attribute custom associated with the page.
java.lang.Object	removeAttribute(java.lang.String name, int scope) Removes the specified custom attribute in the specified scope.
void	removeComponents() Removes all components in this page.
boolean	removeEventListener(java.lang.String evtnm, EventListener listener) Removes an event listener.
boolean	removeVariableResolver(VariableResolver resolver) Removes a name resolve that was added by addVariableResolver(org.zkoss.zk.scripting.VariableResolver).
java.lang.Object	setAttribute(java.lang.String name, java.lang.Object value) Sets the value of the specified custom attribute associated with this page.
java.lang.Object	setAttribute(java.lang.String name, java.lang.Object value, int scope) Sets the value of the specified custom attribute in the specified scope.
void	setId(java.lang.String id) Sets the identifier of this page.
void	setStyle(java.lang.String style) Sets the CSS style of this page.
void	setTitle(java.lang.String title) Sets the title of the desktop this page belongs to (it might contain an expression).
void	setVariable(java.lang.String name, java.lang.Object val) Sets a variable to the namespace (getNamespace()).
void	setZScriptLanguage(java.lang.String zslang) Sets the defafult scripting language which will be assumed if a zscript element doesn't specify any language.
void	unsetVariable(java.lang.String name) Unsets a variable from the namespace (getNamespace()).

Methods inherited from interface org.zkoss.zk.ui.IdSpace

getFellow, getFellowIfAny

Field Detail

PAGE_SCOPE

static final int PAGE_SCOPE

Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same page.

It is also known as the page attributes.

It is the same as getAttributes(int).

See Also:

Constant Field Values

DESKTOP_SCOPE

static final int DESKTOP_SCOPE

Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same desktop.

It is also known as the desktop attributes.

It is the same as Desktop.getAttributes().

See Also:

Constant Field Values

SESSION_SCOPE

static final int SESSION_SCOPE

Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same session.

It is also known as the session attributes.

It is the same as Session.getAttributes().

See Also:

Constant Field Values

APPLICATION_SCOPE

static final int APPLICATION_SCOPE

Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the whole application.

It is also known as the application attributes.

It is the same as WebApp.getAttributes().

See Also:

Constant Field Values

REQUEST_SCOPE

static final int REQUEST_SCOPE

Used with getAttribute(java.lang.String, int) and relevants to denote custom attributes shared by the same request.

It is also known as the request attributes.

It is the same as Execution.getAttributes().

See Also:

Constant Field Values

Method Detail

getId

java.lang.String getId()

Returns ID which is unique in the request (never null).

Note: it returns null when Initiator.doInit(org.zkoss.zk.ui.Page, java.lang.Object[]) is called.

setId

void setId(java.lang.String id)

Sets the identifier of this page.

Note: you can change the page's ID only in Initiator.doInit(org.zkoss.zk.ui.Page, java.lang.Object[]) or ExecutionInit.init(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Execution). Once the page is initialized (by PageCtrl.init(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String)), calling this method will cause an exception.

Throws:

UiException - if the page is initialized, i.e., PageCtrl.init(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String) is called.

getUuid

java.lang.String getUuid()

Returns UUID (universal unique ID) which is unquie in the whole session. The UUID is generated automatically and immutable.

It is mainly used for communication between client and server and you rarely need to access it.

getTitle

java.lang.String getTitle()

Returns the title of the desktop this page belongs to (and evaluate it if it contains an expression).

Default: "".

setTitle

void setTitle(java.lang.String title)

Sets the title of the desktop this page belongs to (it might contain an expression).

getStyle

java.lang.String getStyle()

Returns the CSS style of this page, or empty if not specified.

setStyle

void setStyle(java.lang.String style)

Sets the CSS style of this page.

Note: Unlike setTitle(java.lang.String), you can change the style only in the lifecycle of the loading page.

getRequestPath

java.lang.String getRequestPath()

Returns the request path of this page, or "" if not available.

It is the same as the servlet path (javax.servlet.http.HttpServletRequest's getServletPath), if ZK is running at a servlet container.

See Also:

Execution.getContextPath()

getDesktop

Desktop getDesktop()

Returns the desktop that this page belongs to.

Note: it returns null when Initiator.doInit(org.zkoss.zk.ui.Page, java.lang.Object[]) is called.

getRoots

java.util.Collection getRoots()

Returns a readonly list of the root components.

getAttributes

java.util.Map getAttributes(int scope)

Returns all custom attributes of the specified scope. You could reference them thru componentScope, spaceScope, pageScope, requestScope and desktopScope in zscript and EL.

If scope is PAGE_SCOPE, it means custom attributes shared by components from the same page as this one's.

If scope is DESKTOP_SCOPE, it means custom attributes shared by components from the same desktopas this one's.

Parameters:

scope - APPLICATION_SCOPE, SESSION_SCOPE, PAGE_SCOPE, REQUEST_SCOPE or DESKTOP_SCOPE.

getAttribute

java.lang.Object getAttribute(java.lang.String name,
                              int scope)

Returns the value of the specified custom attribute in the specified scope.

If scope is PAGE_SCOPE, it means custom attributes shared by components from the same page as this one's.

If scope is DESKTOP_SCOPE, it means custom attributes shared by components from the same desktopas this one's.

Parameters:

scope - APPLICATION_SCOPE, SESSION_SCOPE, PAGE_SCOPE, REQUEST_SCOPE or DESKTOP_SCOPE.

setAttribute

java.lang.Object setAttribute(java.lang.String name,
                              java.lang.Object value,
                              int scope)

Sets the value of the specified custom attribute in the specified scope.

If scope is PAGE_SCOPE, it means custom attributes shared by components from the same page as this one's.

If scope is DESKTOP_SCOPE, it means custom attributes shared by components from the same desktopas this one's.

Parameters:

scope - APPLICATION_SCOPE, SESSION_SCOPE, PAGE_SCOPE, REQUEST_SCOPE or DESKTOP_SCOPE.

removeAttribute

java.lang.Object removeAttribute(java.lang.String name,
                                 int scope)

Removes the specified custom attribute in the specified scope.

If scope is PAGE_SCOPE, it means custom attributes shared by components from the same page as this one's.

If scope is DESKTOP_SCOPE, it means custom attributes shared by components from the same desktopas this one's.

Parameters:

scope - APPLICATION_SCOPE, SESSION_SCOPE, PAGE_SCOPE, REQUEST_SCOPE or DESKTOP_SCOPE.

getAttributes

java.util.Map getAttributes()

Returns all custom attributes associated with this page.

getAttribute

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

Returns the value of the specified attribute associated with this page.

setAttribute

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

Sets the value of the specified custom attribute associated with this page.

Note: The attribute is removed (by removeAttribute(java.lang.String, int) if value is null, while setVariable(java.lang.String, java.lang.Object) considers null as a legal value.

Parameters:

value - the value. If null, the attribute is removed.

removeAttribute

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

Removes the specified attribute custom associated with the page.

setVariable

void setVariable(java.lang.String name,
                 java.lang.Object val)

Sets a variable to the namespace (getNamespace()).

It is the same as getNamespace().setVariable(name, value, true).

See Also:

Component.setVariable(java.lang.String, java.lang.Object, boolean), Component.getNamespace()

containsVariable

boolean containsVariable(java.lang.String name)

Returns whether the specified variable is defined.

Note: null is a valid value for variable, so this method is used to know whether a variable is defined. On the other hand, setAttribute(java.lang.String, java.lang.Object, int) actually remove an attribute (by removeAttribute(java.lang.String, int) if value is null.

getVariable

java.lang.Object getVariable(java.lang.String name)

Returns the value of a variable defined in the namespace (getNamespace()).

It is the same as getNamespace().getVariable(name, true).

Differences between getVariable(java.lang.String) and getZScriptVariable(java.lang.String)

getVariable(java.lang.String) returns only variables defined by setVariable(java.lang.String, java.lang.Object) (i.e., a shortcut to Namespace.setVariable(java.lang.String, java.lang.Object, boolean)). On the other hand, getZScriptVariable(java.lang.String) returns these variables and those defined when executing zscripts.

See Also:

Component.getVariable(java.lang.String, boolean), Component.getNamespace()

unsetVariable

void unsetVariable(java.lang.String name)

Unsets a variable from the namespace (getNamespace()).

It is the same as getNamespace().unsetVariable(name, true).

See Also:

Component.unsetVariable(java.lang.String, boolean), Component.getNamespace()

getZScriptClass

java.lang.Class getZScriptClass(java.lang.String clsnm)

Returns the class of the specified name by searching the thread class loader and the classes defined in the loaded interpreters.

Note: it also looks for the class by use of the current thread's class loader.

Returns:

the class, or null if not found

See Also:

getLoadedInterpreters()

getZScriptMethod

Method getZScriptMethod(java.lang.String name,
                        java.lang.Class[] argTypes)

Returns the variable of the specified name by searching the loaded interpreters.

Returns:

the method, or null if not found

See Also:

getLoadedInterpreters()

getZScriptMethod

Method getZScriptMethod(Namespace ns,
                        java.lang.String name,
                        java.lang.Class[] argTypes)

Returns the variable of the specified name by searching the logical scope of the specified namespace for all the loaded interpreters.

It is similar to getZScriptVariable(String), except it uses the specified namespace as a reference to identify the correct scope for searching the variable. If the interpreter does NOT support hierachical scopes, this method is the same as getZScriptVariable(String).

Parameters:

ns - the namespace used as a reference to identify the correct scope for searching the variable. It is ignored if the interpreter doesn't support hierachical scopes. Note: this method doesn't look for any variable stored in ns.

Returns:

the method, or null if not found

Since:

2.4.1

See Also:

getLoadedInterpreters()

getZScriptVariable

java.lang.Object getZScriptVariable(java.lang.String name)

Returns the value of the variable of the specified name by searching the loaded interpreters, if any.

Differences between getVariable(java.lang.String) and getZScriptVariable(java.lang.String)

getVariable(java.lang.String) returns variables defined by setVariable(java.lang.String, java.lang.Object) (i.e., a shortcut to Namespace.setVariable(java.lang.String, java.lang.Object, boolean)). On the other hand, getZScriptVariable(java.lang.String) returns the variables that are defined when executing zscripts.

Returns:

the value of the variable, or null if not found

See Also:

getLoadedInterpreters()

getZScriptVariable

java.lang.Object getZScriptVariable(Namespace ns,
                                    java.lang.String name)

Returns the value of the variable of the specified name by searching the logical scope of the specified namespace for all the loaded interpreters, if any.

It is similar to getZScriptVariable(String), except it uses the specified namespace as a reference to identify the correct scope for searching the variable. If the interpreter does NOT support hierachical scopes, this method is the same as getZScriptVariable(String).

Parameters:

ns - the namespace used as a reference to identify the correct scope for searching the variable. It is ignored if the interpreter doesn't support hierachical scopes. Note: this method doesn't look for any variable stored in ns.

getELVariable

java.lang.Object getELVariable(java.lang.String name)

Returns a variable that is visible to EL expressions.

This method is mainly used to access special variable, such as request parameters (if this page is requested by HTTP).

Note: components that are specified with an ID are already accessible by getVariable(java.lang.String).

addVariableResolver

boolean addVariableResolver(VariableResolver resolver)

Adds a name resolver that will be used to resolve a variable by getVariable(java.lang.String).

Note: the variables resolved by the specified resolver are accessible to both zscript and EL expressions.

Returns:

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

removeVariableResolver

boolean removeVariableResolver(VariableResolver resolver)

Removes a name resolve that was added by addVariableResolver(org.zkoss.zk.scripting.VariableResolver).

Returns:

false if resolved is not added before.

addEventListener

boolean addEventListener(java.lang.String evtnm,
                         EventListener listener)

Adds an event listener to specified event for all components in this page.

Due to performance consideration, unlike Component.addEventListener(java.lang.String, org.zkoss.zk.ui.event.EventListener), all event listeners for the page are deferrable, no matter Deferrable is implemented or not.

Parameters:

evtnm - what event to listen (never null)

Returns:

whether the listener is added; false if it was added before.

See Also:

Component.addEventListener(java.lang.String, org.zkoss.zk.ui.event.EventListener)

removeEventListener

boolean removeEventListener(java.lang.String evtnm,
                            EventListener listener)

Removes an event listener.

Returns:

whether the listener is removed; false if it was never added.

isListenerAvailable

boolean isListenerAvailable(java.lang.String evtnm)

Returns whether the event listener is available.

getListenerIterator

java.util.Iterator getListenerIterator(java.lang.String evtnm)

Returns an iterator for iterating listener for the specified event.

removeComponents

void removeComponents()

Removes all components in this page.

See Also:

Execution.createComponents(String,Component,Map)

invalidate

void invalidate()

Invalidates this page to cause all components to redraw.

getNamespace

Namespace getNamespace()

Returns the namespace used to store variables belonging to the ID space of this page.

See Also:

interpret(java.lang.String, java.lang.String, org.zkoss.zk.scripting.Namespace)

interpret

void interpret(java.lang.String zslang,
               java.lang.String script,
               Namespace ns)

Interpret a script of the specified scripting language against the specified namespace.

Parameters:

zslang - the scripting language. If null, getZScriptLanguage() is assumed.

ns - the namspace. If null, the current namespace is assumed. The current namespace is the event target's namespace (Event.getTarget()), if the thread is processing an event. Otherwise, the current namespace is this page's namespace

getInterpreter

Interpreter getInterpreter(java.lang.String zslang)

Returns the interpreter of the specified scripting language.

The interpreter will be loaded and initialized, if it is not loaded yet.

Parameters:

zslang - the scripting language. If null, getZScriptLanguage() is assumed.

Throws:

InterpreterNotFoundException - if not found.

getLoadedInterpreters

java.util.Collection getLoadedInterpreters()

Returns all loaded interpreters.

getZScriptLanguage

java.lang.String getZScriptLanguage()

Returns the default scripting language which is assumed when a zscript element doesn't specify any language.

Returns:

the default scripting language, say, Java. Never null.

setZScriptLanguage

void setZScriptLanguage(java.lang.String zslang)
                        throws InterpreterNotFoundException

Sets the defafult scripting language which will be assumed if a zscript element doesn't specify any language.

Throws:

InterpreterNotFoundException - if no such language

getFunctionMapper

javax.servlet.jsp.el.FunctionMapper getFunctionMapper()

Returns the function mapper for resolving EL functions, or null if not available.

addFunctionMapper

void addFunctionMapper(javax.servlet.jsp.el.FunctionMapper funmap)

Adds the function mapper in addition to the current one.

The new added function mapper has the higher priority. getFunctionMapper() will return the new

Parameters:

funmap - the new function mapper (null to ignore).

getLanguageDefinition

LanguageDefinition getLanguageDefinition()

Returns the language definition that this page belongs to (never null).

getComponentDefinitionMap

ComponentDefinitionMap getComponentDefinitionMap()

Returns the map of component definitions (never null).

Note: the map is shared among all instance of the same page definition. Any component definition added (by ComponentDefinitionMap.add(org.zkoss.zk.ui.metainfo.ComponentDefinition)) are visible to all other instances of the same page definition. Thus, it is NOT a good idea to change its content.

getComponentDefinition

ComponentDefinition getComponentDefinition(java.lang.String name,
                                           boolean recur)

Returns the component definition of the specified name, or null if not found.

Note: unlike LanguageDefinition.getComponentDefinition(java.lang.String), this method doesn't throw ComponentNotFoundException if not found. It just returns null.

Parameters:

recur - whether to look up the component from getLanguageDefinition()

getComponentDefinition

ComponentDefinition getComponentDefinition(java.lang.Class cls,
                                           boolean recur)

Returns the component definition of the specified class, or null if not found.

Note: unlike LanguageDefinition.getComponentDefinition(java.lang.String), this method doesn't throw ComponentNotFoundException if not found. It just returns null.

Parameters:

recur - whether to look up the component from getLanguageDefinition()