org.zkoss.zk.ui.impl
Class AbstractExecution

java.lang.Object
  org.zkoss.zk.ui.impl.AbstractExecution

All Implemented Interfaces:

Execution, ExecutionCtrl

Direct Known Subclasses:

ExecutionImpl

public abstract class AbstractExecution
extends java.lang.Object
implements Execution, ExecutionCtrl

A skeletal implementation of Execution.

Author:

tomyeh

Field Summary

Fields inherited from interface org.zkoss.zk.ui.Execution

APPEND_PARAM, IGNORE_PARAM, OVERWRITE_URI, PASS_THRU_ATTR

Constructor Summary

protected

AbstractExecution(Desktop desktop, Page creating) Constructs an execution.

Method Summary

void	addAuResponse(java.lang.String key, AuResponse response) Adds an asynchronous response (AuResponse) which will be sent to client at the end of the execution.
Component	createComponents(PageDefinition pagedef, Component parent, java.util.Map arg) Creates components from the specified page definition.
Component[]	createComponents(PageDefinition pagedef, java.util.Map arg) Creates components that don't belong to any page from the specified page definition.
Component	createComponents(java.lang.String uri, Component parent, java.util.Map arg) Creates components from a page file specified by an URI.
Component[]	createComponents(java.lang.String uri, java.util.Map arg) Creates components that don't belong to any page from a page file specified by an URI.
Component	createComponentsDirectly(org.zkoss.idom.Document content, java.lang.String ext, Component parent, java.util.Map arg) Creates components from the raw content specified by a DOM tree.
Component[]	createComponentsDirectly(org.zkoss.idom.Document content, java.lang.String ext, java.util.Map arg) Creates components that don't belong to any page from the raw content specified by a DOM tree.
Component	createComponentsDirectly(java.io.Reader reader, java.lang.String ext, Component parent, java.util.Map arg) Creates components from the raw content read from the specified reader.
Component[]	createComponentsDirectly(java.io.Reader reader, java.lang.String ext, java.util.Map arg) Creates components that don't belong to any page from the raw content read from the specified reader.
Component	createComponentsDirectly(java.lang.String content, java.lang.String ext, Component parent, java.util.Map arg) Creates components from the raw content specified by a string.
Component[]	createComponentsDirectly(java.lang.String content, java.lang.String ext, java.util.Map arg) Creates components that don't belong to any page from the raw content specified by a string.
java.util.Map	getArg() Returns the parameters (aka., arg) if Execution.pushArg(java.util.Map) is called recently, or an empty map if not available.
Page	getCurrentPage() Returns the current page.
PageDefinition	getCurrentPageDefinition() Returns the current page definition, which is pushed when evaluating a page (from a page definition).
Desktop	getDesktop() Returns the desktop for this execution.
Event	getNextEvent() Returns the next event queued by Execution.postEvent(org.zkoss.zk.ui.event.Event), or null if no event queued.
Visualizer	getVisualizer() Returns the Visualizer for this execution (set by ExecutionCtrl.setVisualizer(org.zkoss.zk.ui.sys.Visualizer).
boolean	isActivated() Returns whether this execution is activated.
boolean	isAsyncUpdate(Page page) Returns whether this execution is asynchronous updating the specified page (thru ZK Update Engine).
boolean	isRecovering() Returns whether this execution is in recovering.
void	onActivate() Called when this execution is about to become the current execution Executions.getCurrent().
void	onDeactivate() Called when this execution is about to become a non-current execution.
void	popArg() Pops the parameters (aka., arg) that is pushed by Execution.pushArg(java.util.Map).
void	postEvent(Event evt) Queues an event to the current execution.
void	pushArg(java.util.Map arg) Pushes the parameters (aka., arg) that EL could refer it by the arg variable.
void	sendRedirect(java.lang.String uri) Sends a temporary redirect response to the client using the specified redirect location URL.
void	sendRedirect(java.lang.String uri, java.lang.String target) Sends a temporary redirect response to the client using the specified redirect location URL and redirect to the specified browser window.
void	setCurrentPage(Page curpage) Sets the current page.
void	setCurrentPageDefinition(PageDefinition pgdef) Sets the current page definition.
void	setDesktop(Desktop desktop) Sets the desktop associated with this execution.
void	setVisualizer(Visualizer ei) Sets the Visualizer for this execution.
java.lang.String	toAbsoluteURI(java.lang.String uri, boolean skipInclude) Converts the specified URI to an absolute URI, if uri is related and the current execution is not included (Execution.isIncluded()).
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

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

encodeURL, evaluate, evaluate, forward, forward, getAttribute, getAttributes, getContextPath, getEvaluator, getEvaluator, getLocalAddr, getLocalName, getLocalPort, getNativeRequest, getNativeResponse, getPageDefinition, getPageDefinitionDirectly, getPageDefinitionDirectly, getPageDefinitionDirectly, getParameter, getParameterMap, getParameterValues, getRemoteAddr, getRemoteName, getRemoteUser, getServerName, getServerPort, getUserPrincipal, getVariableResolver, include, include, isBrowser, isExplorer, isExplorer7, isForwarded, isGecko, isIncluded, isMilDevice, isRobot, isSafari, isUserInRole, isVoided, removeAttribute, setAttribute, setVoided

Methods inherited from interface org.zkoss.zk.ui.sys.ExecutionCtrl

addDateHeader, addHeader, getRequestAttribute, setDateHeader, setHeader, setRequestAttribute

Constructor Detail

AbstractExecution

protected AbstractExecution(Desktop desktop,
                            Page creating)

Constructs an execution.

Parameters:

creating - which page is being creating for this execution, or null if none is being created. isAsyncUpdate(org.zkoss.zk.ui.Page) returns based on this.

Method Detail

isAsyncUpdate

public final boolean isAsyncUpdate(Page page)

Description copied from interface: Execution

Returns whether this execution is asynchronous updating the specified page (thru ZK Update Engine).

Specified by:

isAsyncUpdate in interface Execution

Returns:

whether the specified page is being asynchronous updated by this execution. If the specified page is null, this method returns whether this execution is asynchronous updating a page (rather than creating/loading a new page). Each execution remembers the page being creating. All other pages are consided as being asynchronous updated.

getDesktop

public Desktop getDesktop()

Description copied from interface: Execution

Returns the desktop for this execution. Each execution is against exactly one desktop.

Specified by:

getDesktop in interface Execution

postEvent

public void postEvent(Event evt)

Description copied from interface: Execution

Queues an event to the current execution. The event will be processed (as if it is sent from the client).

Specified by:

postEvent in interface Execution

getCurrentPage

public final Page getCurrentPage()

Description copied from interface: ExecutionCtrl

Returns the current page. Though an execution might process many pages, it processes update requests one-by-one and each update request is associated with a page.

Design decision: we put it here because user need not to know about the conccept of the current page.

Specified by:

getCurrentPage in interface ExecutionCtrl

See Also:

Desktop.getPage(java.lang.String)

setCurrentPage

public final void setCurrentPage(Page curpage)

Description copied from interface: ExecutionCtrl

Sets the current page. Though an execution might process many pages, it processes update requests one-by-one and each update request is associated with a page.

Specified by:

setCurrentPage in interface ExecutionCtrl

getCurrentPageDefinition

public PageDefinition getCurrentPageDefinition()

Description copied from interface: ExecutionCtrl

Returns the current page definition, which is pushed when evaluating a page (from a page definition).

Specified by:

getCurrentPageDefinition in interface ExecutionCtrl

setCurrentPageDefinition

public void setCurrentPageDefinition(PageDefinition pgdef)

Description copied from interface: ExecutionCtrl

Sets the current page definition.

Specified by:

setCurrentPageDefinition in interface ExecutionCtrl

Parameters:

pgdef - the page definition. If null, it means it is the same as getCurrentPage().getPageDefinition().

getNextEvent

public Event getNextEvent()

Description copied from interface: ExecutionCtrl

Returns the next event queued by Execution.postEvent(org.zkoss.zk.ui.event.Event), or null if no event queued.

Specified by:

getNextEvent in interface ExecutionCtrl

isActivated

public boolean isActivated()

Description copied from interface: ExecutionCtrl

Returns whether this execution is activated.

Specified by:

isActivated in interface ExecutionCtrl

onActivate

public void onActivate()

Description copied from interface: ExecutionCtrl

Called when this execution is about to become the current execution Executions.getCurrent().

Note: an execution might spread over several threads, so this method might be called several times to activate the states in each thread. Also, an execution might be activated before another is deactivate. For example, when a component includes another page, the second exec is activated to render the included page.

It is used as callback notification.

Note: don't throw any exception in this method.

Specified by:

onActivate in interface ExecutionCtrl

onDeactivate

public void onDeactivate()

Description copied from interface: ExecutionCtrl

Called when this execution is about to become a non-current execution.

It is used as callback notification.

Note: don't throw any exception in this method.

Specified by:

onDeactivate in interface ExecutionCtrl

See Also:

ExecutionCtrl.onActivate()

isRecovering

public boolean isRecovering()

Description copied from interface: ExecutionCtrl

Returns whether this execution is in recovering. In other words, it is in the invocation of FailoverManager.recover(org.zkoss.zk.ui.Session, org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Desktop). If in recovering, no response is sent to the client. It assumes the server is recovering the desktop and all it contains to match the client's status.

Specified by:

isRecovering in interface ExecutionCtrl

setVisualizer

public void setVisualizer(Visualizer ei)

Description copied from interface: ExecutionCtrl

Sets the Visualizer for this execution. It could be anything that UiEngine requires.

Specified by:

setVisualizer in interface ExecutionCtrl

getVisualizer

public Visualizer getVisualizer()

Description copied from interface: ExecutionCtrl

Returns the Visualizer for this execution (set by ExecutionCtrl.setVisualizer(org.zkoss.zk.ui.sys.Visualizer).

Specified by:

getVisualizer in interface ExecutionCtrl

toAbsoluteURI

public java.lang.String toAbsoluteURI(java.lang.String uri,
                                      boolean skipInclude)

Description copied from interface: Execution

Converts the specified URI to an absolute URI, if uri is related and the current execution is not included (Execution.isIncluded()).

Note: an asynchrous update is processed by the update servlet. It is different from the servlet for rendering the ZUML page. In other words, a relative URI won't be interpreted correctly, so you have to invoke this method to convert them if necessary.

In addtions, RequestDispatcher.include doesn't handle related URI well.

Specified by:

toAbsoluteURI in interface Execution

skipInclude - whether not to convert to an absolute URI if the current page is included by another page. When use the include directive, skipInclude shall be true.

createComponents

public Component createComponents(java.lang.String uri,
                                  Component parent,
                                  java.util.Map arg)

Description copied from interface: Execution

Creates components from a page file specified by an URI. The created components become the child of the specified parent, or become the root components of the current page if parent is specified as null.

It loads the page definition from the specified URI (by use Execution.getPageDefinition(java.lang.String) ), and then invokes Execution.createComponents(PageDefinition,Component,Map) to create components.

Specified by:

createComponents in interface Execution

parent - the parent component, or null if you want it to be a root component. If parent is null, the page is assumed to be the current page, which is determined by the execution context.

arg - a map of parameters that is accessible by the arg variable in EL, or by Execution.getArg(). Ignored if null.

See Also:

Execution.createComponents(PageDefinition, Component, Map), Execution.createComponentsDirectly(String, String, Component, Map), Execution.createComponentsDirectly(Document, String, Component, Map), Execution.createComponentsDirectly(Reader, String, Component, Map)

createComponents

public Component createComponents(PageDefinition pagedef,
                                  Component parent,
                                  java.util.Map arg)

Description copied from interface: Execution

Creates components from the specified page definition. The created components become the child of the specified parent, or become the root components of the current page if parent is specified as null.

Specified by:

createComponents in interface Execution

Parameters:

pagedef - the page definition to use. It cannot be null.

parent - the parent component, or null if you want it to be a root component. If parent is null, the page is assumed to be the current page, which is determined by the execution context.

arg - a map of parameters that is accessible by the arg variable in EL, or by Execution.getArg(). Ignored if null.

Returns:

the first component being created.

See Also:

Execution.createComponents(String, Component, Map)

createComponentsDirectly

public Component createComponentsDirectly(java.lang.String content,
                                          java.lang.String ext,
                                          Component parent,
                                          java.util.Map arg)

Description copied from interface: Execution

Creates components from the raw content specified by a string. The created components become the child of the specified parent, or become the root components of the current page if parent is specified as null.

The raw content is parsed to a page defintion by use of Execution.getPageDefinitionDirectly(String, String), and then invokes Execution.createComponents(PageDefinition,Component,Map) to create components.

Specified by:

createComponentsDirectly in interface Execution

Parameters:

content - the raw content of the page. It must be in ZUML.

ext - the default extension if the content doesn't specify an language. In other words, if the content doesn't specify an language, LanguageDefinition.getByExtension(java.lang.String) is called. If extension is null and the content doesn't specify a language, the language called "xul/html" is assumed.

parent - the parent component, or null if you want it to be a root component. If parent is null, the page is assumed to be the current page, which is determined by the execution context.

arg - a map of parameters that is accessible by the arg variable in EL, or by Execution.getArg(). Ignored if null.

See Also:

Execution.createComponents(PageDefinition, Component, Map), Execution.createComponents(String, Component, Map), Execution.createComponentsDirectly(Document, String, Component, Map), Execution.createComponentsDirectly(Reader, String, Component, Map)

createComponentsDirectly

public Component createComponentsDirectly(org.zkoss.idom.Document content,
                                          java.lang.String ext,
                                          Component parent,
                                          java.util.Map arg)

Description copied from interface: Execution

Creates components from the raw content specified by a DOM tree. The created components become the child of the specified parent, or become the root components of the current page if parent is specified as null.

The raw content is parsed to a page defintion by use of Execution.getPageDefinitionDirectly(Document, String), and then invokes Execution.createComponents(PageDefinition,Component,Map) to create components.

Specified by:

createComponentsDirectly in interface Execution

Parameters:

content - the raw content in DOM.

ext - the default extension if the content doesn't specify an language. In other words, if the content doesn't specify an language, LanguageDefinition.getByExtension(java.lang.String) is called. If extension is null and the content doesn't specify a language, the language called "xul/html" is assumed.

parent - the parent component, or null if you want it to be a root component. If parent is null, the page is assumed to be the current page, which is determined by the execution context.

arg - a map of parameters that is accessible by the arg variable in EL, or by Execution.getArg(). Ignored if null.

See Also:

Execution.createComponents(PageDefinition, Component, Map), Execution.createComponents(String, Component, Map), Execution.createComponentsDirectly(Document, String, Component, Map), Execution.createComponentsDirectly(Reader, String, Component, Map)

createComponentsDirectly

public Component createComponentsDirectly(java.io.Reader reader,
                                          java.lang.String ext,
                                          Component parent,
                                          java.util.Map arg)
                                   throws java.io.IOException

Description copied from interface: Execution

Creates components from the raw content read from the specified reader. The created components become the child of the specified parent, or become the root components of the current page if parent is specified as null.

The raw content is loaded and parsed to a page defintion by use of Execution.getPageDefinitionDirectly(Reader,String), and then invokes Execution.createComponents(PageDefinition,Component,Map) to create components.

Specified by:

createComponentsDirectly in interface Execution

Parameters:

reader - the reader to retrieve the raw content in ZUML.

ext - the default extension if the content doesn't specify an language. In other words, if the content doesn't specify an language, LanguageDefinition.getByExtension(java.lang.String) is called. If extension is null and the content doesn't specify a language, the language called "xul/html" is assumed.

parent - the parent component, or null if you want it to be a root component. If parent is null, the page is assumed to be the current page, which is determined by the execution context.

arg - a map of parameters that is accessible by the arg variable in EL, or by Execution.getArg(). Ignored if null.

Throws:

java.io.IOException

See Also:

Execution.createComponents(PageDefinition, Component, Map), Execution.createComponents(String, Component, Map), Execution.createComponentsDirectly(Document, String, Component, Map), Execution.createComponentsDirectly(String, String, Component, Map)

createComponents

public Component[] createComponents(java.lang.String uri,
                                    java.util.Map arg)

Description copied from interface: Execution

Creates components that don't belong to any page from a page file specified by an URI.

It loads the page definition from the specified URI (by use Execution.getPageDefinition(java.lang.String) ), and then invokes Execution.createComponents(PageDefinition,Component,Map) to create components.

Specified by:

createComponents in interface Execution

arg - a map of parameters that is accessible by the arg variable in EL, or by Execution.getArg(). Ignored if null.

See Also:

Execution.createComponents(PageDefinition, Map), Execution.createComponentsDirectly(String, String, Map), Execution.createComponentsDirectly(Document, String, Map), Execution.createComponentsDirectly(Reader, String, Map)

createComponents

public Component[] createComponents(PageDefinition pagedef,
                                    java.util.Map arg)

Description copied from interface: Execution

Creates components that don't belong to any page from the specified page definition.

Specified by:

createComponents in interface Execution

Parameters:

pagedef - the page definition to use. It cannot be null.

arg - a map of parameters that is accessible by the arg variable in EL, or by Execution.getArg(). Ignored if null.

Returns:

the first component being created.

See Also:

Execution.createComponents(String, Map)

createComponentsDirectly

public Component[] createComponentsDirectly(java.lang.String content,
                                            java.lang.String ext,
                                            java.util.Map arg)

Description copied from interface: Execution

Creates components that don't belong to any page from the raw content specified by a string.

The raw content is parsed to a page defintion by use of Execution.getPageDefinitionDirectly(String, String), and then invokes Execution.createComponents(PageDefinition,Component,Map) to create components.

Specified by:

createComponentsDirectly in interface Execution

Parameters:

content - the raw content of the page. It must be in ZUML.

ext - the default extension if the content doesn't specify an language. In other words, if the content doesn't specify an language, LanguageDefinition.getByExtension(java.lang.String) is called. If extension is null and the content doesn't specify a language, the language called "xul/html" is assumed.

arg - a map of parameters that is accessible by the arg variable in EL, or by Execution.getArg(). Ignored if null.

See Also:

Execution.createComponents(PageDefinition, Map), Execution.createComponents(String, Map), Execution.createComponentsDirectly(Document, String, Map), Execution.createComponentsDirectly(Reader, String, Map)

createComponentsDirectly

public Component[] createComponentsDirectly(org.zkoss.idom.Document content,
                                            java.lang.String ext,
                                            java.util.Map arg)

Description copied from interface: Execution

Creates components that don't belong to any page from the raw content specified by a DOM tree.

The raw content is parsed to a page defintion by use of Execution.getPageDefinitionDirectly(Document, String), and then invokes Execution.createComponents(PageDefinition,Component,Map) to create components.

Specified by:

createComponentsDirectly in interface Execution

Parameters:

content - the raw content in DOM.

ext - the default extension if the content doesn't specify an language. In other words, if the content doesn't specify an language, LanguageDefinition.getByExtension(java.lang.String) is called. If extension is null and the content doesn't specify a language, the language called "xul/html" is assumed.

arg - a map of parameters that is accessible by the arg variable in EL, or by Execution.getArg(). Ignored if null.

See Also:

Execution.createComponents(PageDefinition, Map), Execution.createComponents(String, Map), Execution.createComponentsDirectly(Document, String, Map), Execution.createComponentsDirectly(Reader, String, Map)

createComponentsDirectly

public Component[] createComponentsDirectly(java.io.Reader reader,
                                            java.lang.String ext,
                                            java.util.Map arg)
                                     throws java.io.IOException

Description copied from interface: Execution

Creates components that don't belong to any page from the raw content read from the specified reader.

The raw content is loaded and parsed to a page defintion by use of Execution.getPageDefinitionDirectly(Reader,String), and then invokes Execution.createComponents(PageDefinition,Component,Map) to create components.

Specified by:

createComponentsDirectly in interface Execution

Parameters:

reader - the reader to retrieve the raw content in ZUML.

ext - the default extension if the content doesn't specify an language. In other words, if the content doesn't specify an language, LanguageDefinition.getByExtension(java.lang.String) is called. If extension is null and the content doesn't specify a language, the language called "xul/html" is assumed.

arg - a map of parameters that is accessible by the arg variable in EL, or by Execution.getArg(). Ignored if null.

Throws:

java.io.IOException

See Also:

Execution.createComponents(PageDefinition, Map), Execution.createComponents(String, Map), Execution.createComponentsDirectly(Document, String, Map), Execution.createComponentsDirectly(String, String, Map)

sendRedirect

public void sendRedirect(java.lang.String uri)

Description copied from interface: Execution

Sends a temporary redirect response to the client using the specified redirect location URL.

It is the same as sendRedirect(url, null).

After calling this method, the caller shall end the processing immediately (by returning). All pending requests and events will be dropped.

Specified by:

sendRedirect in interface Execution

Parameters:

uri - the URI to redirect to, or null to reload the same page

sendRedirect

public void sendRedirect(java.lang.String uri,
                         java.lang.String target)

Description copied from interface: Execution

Sends a temporary redirect response to the client using the specified redirect location URL and redirect to the specified browser window.

After calling this method, the caller shall end the processing immediately (by returning). All pending requests and events will be dropped.

Note: if you specify target other than null and "_self", it'll fail if the browser prevent the server to popup a window.

Specified by:

sendRedirect in interface Execution

Parameters:

uri - the URI to redirect to, or null to reload the same page

target - the name of the browser window that send-redirect will load the sepcified URI, or null if the current browser window is used.

getArg

public java.util.Map getArg()

Description copied from interface: Execution

Returns the parameters (aka., arg) if Execution.pushArg(java.util.Map) is called recently, or an empty map if not available.

The use of parameters is application dependent. ZK only provides the way to store (Execution.pushArg(java.util.Map) and to restore Execution.popArg(). And, let the parameters being accessible in EL by referring it as the arg variable.

Currently, Execution.createComponents(String,Component,Map) and similar methods use this mechanism to let caller customize a page definition.

Notice that Execution.createComponents(String,Component,Map) pops arg after creating components, and before processing any event. In other words, it is not aviable for event listener, including onCreate. However, CreateEvent.getArg() preserves the map for its event listeners.

Specified by:

getArg in interface Execution

pushArg

public void pushArg(java.util.Map arg)

Description copied from interface: Execution

Pushes the parameters (aka., arg) that EL could refer it by the arg variable. Remember to call Execution.popArg() in the finally clause.

Specified by:

pushArg in interface Execution

See Also:

Execution.getArg()

popArg

public void popArg()

Description copied from interface: Execution

Pops the parameters (aka., arg) that is pushed by Execution.pushArg(java.util.Map).

It never throws an exception.

Specified by:

popArg in interface Execution

See Also:

Execution.getArg()

addAuResponse

public void addAuResponse(java.lang.String key,
                          AuResponse response)

Description copied from interface: Execution

Adds an asynchronous response (AuResponse) which will be sent to client at the end of the execution.

If AuResponse.getDepends() is not null, the response depends on the returned componet. In other words, the response is removed if the component is removed. If it is null, the response is component-independent.

Specified by:

addAuResponse in interface Execution

Parameters:

key - could be anything. The second invocation of this method in the same execution with the same key will override the previous one.

setDesktop

public void setDesktop(Desktop desktop)

Description copied from interface: ExecutionCtrl

Sets the desktop associated with this execution. You rarely need to use this method, since the desktop is associated when this execution is created.

Currently, it is used to communicate between WebManager.newDesktop and DesktopImpl's constructor.

Specified by:

setDesktop in interface ExecutionCtrl

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object