Package org.zkoss.zk.ui

Class Executions

java.lang.Object

org.zkoss.zk.ui.Executions

Direct Known Subclasses:

ExecutionsCtrl

public class Executions
extends Object

Utilities to access Execution.

Author:

tomyeh

Field Summary

Fields

Modifier and Type	Field	Description
protected static final ThreadLocal<Execution>	_exec	Stores the current Execution.

Constructor Summary

Constructors

Constructor	Description
Executions()

Method Summary

Modifier and Type	Method	Description
static final void	activate(Desktop desktop)	Activates a thread to allow it access the given desktop synchronously.
static final boolean	activate(Desktop desktop, long timeout)	Activates a thread to allow it access the given desktop synchronously, or until a certain amount of time has elapsed.
static final Component	createComponents(String uri, Component parent, Map<?,?> arg)	Creates components from a page file specified by an URI.
static Component[]	createComponents(String uri, Page page, org.zkoss.xel.VariableResolver resolver, Map<?,?> arg)	Creates components that belong to the given page from a page file specified by an URI.
static final Component	createComponents(PageDefinition pagedef, Component parent, Map<?,?> arg)	Creates components based on the specified page definition.
static Component[]	createComponents(WebApp wapp, String uri, Map<?,?> arg)	Creates components that don't belong to any page from a page file specified by an URI.
static Component[]	createComponents(WebApp wapp, PageDefinition pagedef, Map<?,?> arg)	Creates components that don't belong to any page from the specified page definition.
static Component	createComponentsDirectly(Reader reader, String extension, Component parent, Map<?,?> arg)	Creates components from the raw content read from the specified reader.
static final Component	createComponentsDirectly(String content, String extension, Component parent, Map<?,?> arg)	Creates components from the raw content specified by a string.
static final Component	createComponentsDirectly(org.zkoss.idom.Document content, String extension, Component parent, Map<?,?> arg)	Creates components from the raw content specified by a DOM tree.
static Component[]	createComponentsDirectly(WebApp wapp, Reader reader, String extension, Map<?,?> arg)	Creates components that don't belong to any page from the raw content read from the specified reader.
static Component[]	createComponentsDirectly(WebApp wapp, String content, String extension, Map<?,?> arg)	Creates components that don't belong to any page from the raw content specified by a string.
static Component[]	createComponentsDirectly(WebApp wapp, org.zkoss.idom.Document content, String extension, Map<?,?> arg)	Creates components that don't belong to any page from the raw content specified by a DOM tree.
static final void	deactivate(Desktop desktop)	Deactivates a thread that has invoked activate(org.zkoss.zk.ui.Desktop) successfully.
static final URL	encodeToURL(String uri)	Encodes the specified URL into an instance of URL.
static final String	encodeURL(String uri)	Encodes the specified URL.
static final Object	evaluate(Component comp, String expr, Class expectedType)	Evaluates the specified expression by use of the current context (getCurrent()).
static final Object	evaluate(Page page, String expr, Class expectedType)	Evaluates the specified expression with the resolver of the current execution (getCurrent()).
static void	forward(String page)	A shortcut of Executions.getCurrent().forward(page).
static final Execution	getCurrent()	Returns the current execution.
static final Evaluator	getEvaluator(Component comp, Class<? extends org.zkoss.xel.ExpressionFactory> expfcls)	Returns the evaluator of the current execution.
static final Evaluator	getEvaluator(Page page, Class<? extends org.zkoss.xel.ExpressionFactory> expfcls)	Returns the evaluator of the current execution.
static PageDefinition	getPageDefinition(WebApp wapp, String uri)	Returns the page definition from the page file specified by an URI.
PageDefinition	getPageDefinitionDirectly(WebApp wapp, Reader reader, String extension)	Reads the raw content from a reader and converts it into a page definition.
PageDefinition	getPageDefinitionDirectly(WebApp wapp, String content, String extension)	Converts the specified page content to a page definition.
PageDefinition	getPageDefinitionDirectly(WebApp wapp, org.zkoss.idom.Document content, String extension)	Converts the specified page content, in DOM, to a page definition.
static void	include(String page)	A shortcut of Executions.getCurrent().include(page).
static final void	notify(Object mutex)	Wakes up a single event processing thread that is waiting on the specified object.
static final void	notify(Desktop desktop, Object mutex)	Wakes up a single event processing thread for the specified desktop that is waiting on the specified object.
static final void	notifyAll(Object mutex)	Wakes up all event processing thread that are waiting on the specified object.
static final void	notifyAll(Desktop desktop, Object mutex)	Wakes up all event processing threads for the specified desktop that are waiting on the specified object.
static <T extends Event> void	schedule(Desktop desktop, EventListener<T> task, T event)	Schedules a task to run under the server push of the given desktop asynchronously.
static void	sendRedirect(String uri)	Sends a temporary redirect response to the client using the specified redirect location URL by use of the current execution, getCurrent().
static final void	wait(Object mutex)	Suspends the current processing of an event and wait until the other thread invokes notify(Object), notifyAll(Object), notify(Desktop, Object) or notifyAll(Desktop, Object) for the specified object.

Methods inherited from class java.lang.Object

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

Field Details

_exec

protected static final ThreadLocal<Execution> _exec

Stores the current Execution.

Constructor Details

Executions

public Executions()

Method Details

getCurrent

public static final Execution getCurrent()

Returns the current execution.

getEvaluator

public static final Evaluator getEvaluator(Page page,
 Class<? extends org.zkoss.xel.ExpressionFactory> expfcls)

Returns the evaluator of the current execution. It is usually used to parse the expression into Expression or used with ExValue. for performance improvement.

Parameters:

page - the page that this evaluator is associated. If null, the current page and then the first page is assumed.

expfcls - the implementation of ExpressionFactory, or null to use the default (Configuration.getExpressionFactoryClass().

Since:

3.0.0

getEvaluator

public static final Evaluator getEvaluator(Component comp,
 Class<? extends org.zkoss.xel.ExpressionFactory> expfcls)

Returns the evaluator of the current execution. It is a shortcut of getEvaluator(comp != null ? comp.getPage(): null)

Parameters:

comp - the component to retrieve the page for the evaluator

expfcls - the implementation of ExpressionFactory, or null to use the default (Configuration.getExpressionFactoryClass().

Since:

3.0.0

evaluate

public static final Object evaluate(Component comp,
 String expr,
 Class expectedType)

Evaluates the specified expression by use of the current context (getCurrent()).

The function mapper is retrieved from component's page's function mapper (Page.getFunctionMapper()). If null, the current page, if any, is used to retrieve the mapper.

For better performance, you can use the instance returned by getEvaluator(org.zkoss.zk.ui.Page, java.lang.Class<? extends org.zkoss.xel.ExpressionFactory>) to parse and cached the parsed expression. ExValue is a utility class to simply the task.

Parameters:

comp - as the self variable (ignored if null)

evaluate

public static final Object evaluate(Page page,
 String expr,
 Class expectedType)

Evaluates the specified expression with the resolver of the current execution (getCurrent()).

The function mapper is retrieved from page's function mapper (Page.getFunctionMapper()). If null, the current page, if any, is used to retrieve the mapper.

For better performance, you can use the instance returned by getEvaluator(org.zkoss.zk.ui.Page, java.lang.Class<? extends org.zkoss.xel.ExpressionFactory>) to parse and cached the parsed expression. ExValue is a utility class to simply the task.

Parameters:

page - used as the self variable and to retrieve the function mapper if funmap is not defined. Ignored if null.

encodeURL

public static final String encodeURL(String uri)

Encodes the specified URL.

It resolves "*" contained in URI, if any, to the proper Locale, and the browser code. Refer to Servlets.locate(jakarta.servlet.ServletContext, ServletRequest, String, Locator) for details.

Throws:

NullPointerException - if the current execution is not available.

See Also:

• encodeURL(java.lang.String)

encodeToURL

public static final URL encodeToURL(String uri)
                             throws MalformedURLException

Encodes the specified URL into an instance of URL. It is similar to encodeURL(java.lang.String), except it returns an instance of URL.

Throws:

NullPointerException - if the current execution is not available.

MalformedURLException - if failed to convert it to a legal URL

Since:

3.5.0

createComponents

public static final Component createComponents(String uri,
 Component parent,
 Map<?,?> arg)

Creates components from a page file specified by an URI. Shortcut to Execution.createComponents(String, Component, Map).

Parameters:

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. In other words, the new component will be the root component of the current page if parent is 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:

• createComponents(PageDefinition, Component, Map)

createComponents

public static final Component createComponents(PageDefinition pagedef,
 Component parent,
 Map<?,?> arg)

Creates components based on the specified page definition. Shortcut to Execution.createComponents(PageDefinition, Component, Map).

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. In other words, the new component will be the root component of the current page if parent is 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:

• createComponents(String, Component, Map)

createComponents

public static Component[] createComponents(WebApp wapp,
 PageDefinition pagedef,
 Map<?,?> arg)

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

Unlike createComponents(PageDefinition,Component,Map), this method can be invoked without the current execution, such as a working thread. In this case, the wapp argument must be specified.

Parameters:

wapp - the Web application. It is optional and used only if no current execution (e.g., in a working thread). The instance of WebApp can be retrieved by use of WebManager.getWebApp(), while the instance of WebManager can be retrieved by WebManager.getWebManager(jakarta.servlet.ServletContext)

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:

all top-level components being created.

Since:

3.6.2

See Also:

• createComponents(WebApp, String, Map)

createComponents

public static Component[] createComponents(WebApp wapp,
 String uri,
 Map<?,?> arg)

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 getPageDefinition(org.zkoss.zk.ui.WebApp, java.lang.String) ), and then invokes createComponents(WebApp,PageDefinition,Map) to create components.

Unlike createComponents(String,Component,Map), this method can be invoked without the current execution, such as a working thread. In this case, the wapp argument must be specified.

Parameters:

wapp - the Web application. It is optional and used only if no current execution (e.g., in a working thread). The instance of WebApp can be retrieved by use of WebManager.getWebApp(), while the instance of WebManager can be retrieved by WebManager.getWebManager(jakarta.servlet.ServletContext)

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

Returns:

all top-level components being created.

Since:

3.6.2

See Also:

• createComponents(WebApp, PageDefinition, Map)
• createComponentsDirectly(WebApp, String, String, Map)
• createComponentsDirectly(WebApp, Document, String, Map)
• createComponentsDirectly(WebApp, Reader, String, Map)

createComponents

public static Component[] createComponents(String uri,
 Page page,
 org.zkoss.xel.VariableResolver resolver,
 Map<?,?> arg)

Creates components that belong to the given page from a page file specified by an URI.

Parameters:

page - the page, or null if you want it to attach the created components.

resolver - the variable resolver used to resolve variables. Ignored if null.

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

Returns:

all top-level components being created.

Since:

8.0.1

See Also:

• createComponents(WebApp, PageDefinition, Map)
• createComponentsDirectly(WebApp, String, String, Map)
• createComponentsDirectly(WebApp, Document, String, Map)
• createComponentsDirectly(WebApp, Reader, String, Map)

createComponentsDirectly

public static final Component createComponentsDirectly(String content,
 String extension,
 Component parent,
 Map<?,?> arg)

Creates components from the raw content specified by a string. Shortcut to Execution.createComponentsDirectly(String, String, Component, Map).

Parameters:

content - the raw content of the page. It must be a XML and compliant to the page format (such as ZUL).

extension - 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. In other words, the new component will be the root component of the current page if parent is 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:

• createComponents(PageDefinition, Component, Map)
• createComponents(String, Component, Map)
• createComponentsDirectly(Document, String, Component, Map)
• createComponentsDirectly(Reader, String, Component, Map)

createComponentsDirectly

public static final Component createComponentsDirectly(org.zkoss.idom.Document content,
 String extension,
 Component parent,
 Map<?,?> arg)

Creates components from the raw content specified by a DOM tree. Shortcut to Execution.createComponentsDirectly(Document, String, Component, Map).

Parameters:

content - the raw content in DOM.

extension - 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. In other words, the new component will be the root component of the current page if parent is 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:

• createComponents(PageDefinition, Component, Map)
• createComponents(String, Component, Map)
• createComponentsDirectly(String, String, Component, Map)
• createComponentsDirectly(Reader, String, Component, Map)

createComponentsDirectly

public static Component createComponentsDirectly(Reader reader,
 String extension,
 Component parent,
 Map<?,?> arg)
                                          throws IOException

Creates components from the raw content read from the specified reader. Shortcut to Execution.createComponentsDirectly(Reader, String, Component, Map).

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

Parameters:

reader - the reader to retrieve the raw content.

extension - 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. In other words, the new component will be the root component of the current page if parent is 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.

Throws:

IOException

See Also:

• createComponents(PageDefinition, Component, Map)
• createComponents(String, Component, Map)
• createComponentsDirectly(Document, String, Component, Map)
• createComponentsDirectly(String, String, Component, Map)

createComponentsDirectly

public static Component[] createComponentsDirectly(WebApp wapp,
 String content,
 String extension,
 Map<?,?> arg)

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 definition by use of getPageDefinitionDirectly(WebApp,String,String), and then invokes createComponents(WebApp,PageDefinition,Map) to create components.

Unlike createComponentsDirectly(String,String,Component,Map), this method can be invoked without the current execution, such as a working thread. In this case, the wapp argument must be specified.

Parameters:

wapp - the Web application. It is optional and used only if no current execution (e.g., in a working thread). The instance of WebApp can be retrieved by use of WebManager.getWebApp(), while the instance of WebManager can be retrieved by WebManager.getWebManager(jakarta.servlet.ServletContext)

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

extension - 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.

Returns:

all top-level components being created.

Since:

3.6.2

See Also:

• createComponents(WebApp, PageDefinition, Map)
• createComponents(WebApp, String, Map)
• createComponentsDirectly(WebApp, Document, String, Map)
• createComponentsDirectly(WebApp, Reader, String, Map)

createComponentsDirectly

public static Component[] createComponentsDirectly(WebApp wapp,
 org.zkoss.idom.Document content,
 String extension,
 Map<?,?> arg)

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 definition by use of getPageDefinitionDirectly(WebApp,Document, String), and then invokes createComponents(WebApp,PageDefinition,Map) to create components.

Unlike createComponentsDirectly(Document,String,Component,Map), this method can be invoked without the current execution, such as a working thread. In this case, the wapp argument must be specified.

Parameters:

wapp - the Web application. It is optional and used only if no current execution (e.g., in a working thread). The instance of WebApp can be retrieved by use of WebManager.getWebApp(), while the instance of WebManager can be retrieved by WebManager.getWebManager(jakarta.servlet.ServletContext)

content - the raw content in DOM.

extension - 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.

Returns:

all top-level components being created.

Since:

3.6.2

See Also:

• createComponents(WebApp, PageDefinition, Map)
• createComponents(WebApp, String, Map)
• createComponentsDirectly(WebApp, Document, String, Map)
• createComponentsDirectly(WebApp, Reader, String, Map)

createComponentsDirectly

public static Component[] createComponentsDirectly(WebApp wapp,
 Reader reader,
 String extension,
 Map<?,?> arg)
                                            throws IOException

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

Unl

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

Unlike createComponentsDirectly(Reader,String,Component,Map), this method can be invoked without the current execution, such as a working thread. In this case, the wapp argument must be specified.

Parameters:

wapp - the Web application. It is optional and used only if no current execution (e.g., in a working thread). The instance of WebApp can be retrieved by use of WebManager.getWebApp(), while the instance of WebManager can be retrieved by WebManager.getWebManager(jakarta.servlet.ServletContext)

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

extension - 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.

Returns:

all top-level components being created.

Throws:

IOException

Since:

3.6.2

See Also:

• createComponents(WebApp, PageDefinition, Map)
• createComponents(WebApp, String, Map)
• createComponentsDirectly(WebApp, Document, String, Map)
• createComponentsDirectly(WebApp, String, String, Map)

getPageDefinition

public static PageDefinition getPageDefinition(WebApp wapp,
 String uri)

Returns the page definition from the page file specified by an URI.

Like createComponents(WebApp,PageDefinition,Map), this method can be invoked without the current execution, such as a working thread. In this case, the wapp argument must be specified.

Parameters:

wapp - the Web application. It is optional and used only if no current execution (e.g., in a working thread). The instance of WebApp can be retrieved by use of WebManager.getWebApp(), while the instance of WebManager can be retrieved by WebManager.getWebManager(jakarta.servlet.ServletContext)

uri - the URI of the page file.

Since:

3.6.2

See Also:

• getPageDefinitionDirectly(WebApp, String, String)
• getPageDefinitionDirectly(WebApp, Document, String)
• getPageDefinitionDirectly(WebApp, Reader, String)

getPageDefinitionDirectly

public PageDefinition getPageDefinitionDirectly(WebApp wapp,
 String content,
 String extension)

Converts the specified page content to a page definition.

Like createComponents(WebApp,PageDefinition,Map), this method can be invoked without the current execution, such as a working thread. In this case, the wapp argument must be specified.

Parameters:

wapp - the Web application. It is optional and used only if no current execution (e.g., in a working thread). The instance of WebApp can be retrieved by use of WebManager.getWebApp(), while the instance of WebManager can be retrieved by WebManager.getWebManager(jakarta.servlet.ServletContext)

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

extension - 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.

Since:

3.6.2

See Also:

• getPageDefinitionDirectly(WebApp, Document, String)
• getPageDefinitionDirectly(WebApp, Reader, String)
• getPageDefinition(org.zkoss.zk.ui.WebApp, java.lang.String)

getPageDefinitionDirectly

public PageDefinition getPageDefinitionDirectly(WebApp wapp,
 org.zkoss.idom.Document content,
 String extension)

Converts the specified page content, in DOM, to a page definition.

Like createComponentsDirectly(WebApp,Document,String,Map), this method can be invoked without the current execution, such as a working thread. In this case, the wapp argument must be specified.

Parameters:

wapp - the Web application. It is optional and used only if no current execution (e.g., in a working thread). The instance of WebApp can be retrieved by use of WebManager.getWebApp(), while the instance of WebManager can be retrieved by WebManager.getWebManager(jakarta.servlet.ServletContext)

content - the raw content of the page in DOM.

extension - 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.

Since:

3.6.2

See Also:

• getPageDefinitionDirectly(WebApp, String, String)
• getPageDefinitionDirectly(WebApp, Reader, String)
• getPageDefinition(org.zkoss.zk.ui.WebApp, java.lang.String)

getPageDefinitionDirectly

public PageDefinition getPageDefinitionDirectly(WebApp wapp,
 Reader reader,
 String extension)
                                         throws IOException

Reads the raw content from a reader and converts it into a page definition.

Like createComponentsDirectly(WebApp,Reader,String,Map), this method can be invoked without the current execution, such as a working thread. In this case, the wapp argument must be specified.

Parameters:

wapp - the Web application. It is optional and used only if no current execution (e.g., in a working thread). The instance of WebApp can be retrieved by use of WebManager.getWebApp(), while the instance of WebManager can be retrieved by WebManager.getWebManager(jakarta.servlet.ServletContext)

reader - used to input the raw content of the page. It must be in ZUML.

extension - 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.

Throws:

IOException

Since:

3.6.2

See Also:

• getPageDefinitionDirectly(WebApp, String, String)
• getPageDefinitionDirectly(WebApp, Document, String)
• getPageDefinition(org.zkoss.zk.ui.WebApp, java.lang.String)

sendRedirect

public static void sendRedirect(String uri)

Sends a temporary redirect response to the client using the specified redirect location URL by use of the current execution, getCurrent().

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

Parameters:

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

See Also:

• Execution.sendRedirect(java.lang.String)

include

public static void include(String page)
                    throws IOException

A shortcut of Executions.getCurrent().include(page).

Throws:

IOException

See Also:

• Execution.include(java.io.Writer,String,Map,int)
• Execution.include(String)

forward

public static void forward(String page)
                    throws IOException

A shortcut of Executions.getCurrent().forward(page).

Throws:

IOException

See Also:

• Execution.forward(java.io.Writer,String,Map,int)
• Execution.forward(String)

wait

public static final void wait(Object mutex)
                       throws InterruptedException,
SuspendNotAllowedException

Suspends the current processing of an event and wait until the other thread invokes notify(Object), notifyAll(Object), notify(Desktop, Object) or notifyAll(Desktop, Object) for the specified object.

It can only be called when the current thread is processing an event. And, when called, the current processing is suspended and ZK continues to process the next event and finally render the result.

It is typical use to implement a modal dialog where it won't return until the modal dialog ends.

Parameters:

mutex - any non-null object to identify what to notify. It must be same object passed to notify(Desktop, Object). If there is racing issue, you have to enclose it with synchronized (though it is optional).

Throws:

UiException - if it is called not during event processing.

SuspendNotAllowedException - if there are too many suspended exceptions. Deployers can control the maximal allowed number of suspended exceptions by specifying max-suspended-thread in zk.xml, or invoking Configuration.setMaxSuspendedThreads(int).

InterruptedException

notify

public static final void notify(Object mutex)

Wakes up a single event processing thread that is waiting on the specified object.

Unlike notify(Desktop, Object), this method can be invoked only in the event listener that processing the same desktop. In addition, this method can be called under the event listener.

Use notify(Desktop, Object) if you want to notify in other thread, such as a working thread.

Parameters:

mutex - any non-null object to identify what to notify. It must be same object passed to wait(java.lang.Object). If there is racing issue, you have to enclose it with synchronized (though it is optional).

Throws:

UiException - if it is called not during event processing.

See Also:

• notify(Desktop, Object)
• notifyAll(Object)

notify

public static final void notify(Desktop desktop,
 Object mutex)

Wakes up a single event processing thread for the specified desktop that is waiting on the specified object.

Unlike notify(Object), this method can be called any time. It is designed to let working threads resume an event processing thread.

Notice: if this method is NOT called in an event processing thread, the resumed thread won't execute until the next request is received. To enforce it happen, you might use the timer component (found in ZUL).

Notice: to resolve racing issue, you usually need to follow this pattern.

        //Event Handling Thread
        synchronized (mutex) {
        final WorkingThread worker = new WorkingThread(desktop);
        synchronized (mutex) {
                worker.start();
                Executions.wait(mutex);
        }
        ....
        }
        //Working Thread
        public void run() {
        ....
        synchronized (mutex) {
                Executions.notify(desktop, mutex);
        }
        }
         

Parameters:

desktop - the desktop which the suspended thread is processing. It must be the same desktop of the suspended thread.

mutex - any non-null object to identify what to notify. It must be same object passed to wait(java.lang.Object). If there is racing issue, you have to enclose it with synchronized (though it is optional).

See Also:

• notify(Object)
• notifyAll(Desktop, Object)

notifyAll

public static final void notifyAll(Object mutex)

Wakes up all event processing thread that are waiting on the specified object.

Unlike notify(Desktop, Object), this method can be invoked only in the event listener that processing the same desktop. In addition, this method can be called under the event listener.

Use notifyAll(Desktop, Object) if you want to notify in other thread, such as a working thread.

Parameters:

mutex - any non-null object to identify what to notify. It must be same object passed to wait(java.lang.Object). If there is racing issue, you have to enclose it with synchronized (though it is optional).

Throws:

UiException - if it is called not during event processing.

See Also:

• notify(Desktop, Object)
• notifyAll(Object)

notifyAll

public static final void notifyAll(Desktop desktop,
 Object mutex)

Wakes up all event processing threads for the specified desktop that are waiting on the specified object.

Unlike notifyAll(Object), this method can be called any time. It is designed to let working threads resume an event processing thread.

Notice: if this method is NOT called in an event processing thread, the resumed thread won't execute until the next request is received. To enforce it happen, you might use the timer component (found in ZUL).

Notice: to resolve racing issue, you usually need to follow this pattern.

        //Event Handling Thread
        synchronized (mutex) {
        final WorkingThread worker = new WorkingThread(desktop);
        synchronized (mutex) {
                worker.start();
                Executions.wait(mutex);
        }
        ....
        }
        //Working Thread
        public void run() {
        ....
        synchronized (mutex) {
                Executions.notifyAll(desktop, mutex);
        }
        }
         

Parameters:

desktop - the desktop which the suspended thread is processing. It must be the same desktop of the suspended thread.

mutex - any non-null object to identify what to notify. It must be same object passed to wait(java.lang.Object). If there is racing issue, you have to enclose it with synchronized (though it is optional).

See Also:

• notify(Object)
• notifyAll(Desktop, Object)

schedule

public static <T extends Event> void schedule(Desktop desktop,
 EventListener<T> task,
 T event)

Schedules a task to run under the server push of the given desktop asynchronously. The caller can be any thread, not limited to the event listener of the given desktop.

The task is executed when the server push of the given desktop is granted. The task is executed asynchronously. That is, this method return without waiting for the task to be executed.

The task is executed in the thread serving the server-push request, so no additional thread will be created. It is safe to use in a clustering environment.

The task is represented by an event listener. When the server push is ready to serve the given task, EventListener.onEvent(T) is called with the given event.

Like activate(org.zkoss.zk.ui.Desktop), this method can be called anywhere, not limited to the event listener of the given desktop. It can be called even if there is no current execution.

Alternative to schedule(org.zkoss.zk.ui.Desktop, org.zkoss.zk.ui.event.EventListener<T>, T), you could use activate(org.zkoss.zk.ui.Desktop)/deactivate(org.zkoss.zk.ui.Desktop) if you prefer something to be done synchronously.

The server-push is disabled by default. To use it, you have to enable it first with Desktop.enableServerPush(boolean) for the given desktop. Once enabled, you can use as many as server-push threads you like (for the desktop with the server-push feature enabled).

Parameters:

task - the task to execute

event - the event to be passed to the task (i.e., the event listener). It could null or any instance as long as the task recognizes it.

Throws:

IllegalStateException - if the server push is not enabled.

DesktopUnavailableException - if the desktop is removed (when activating).

Since:

5.0.6

activate

public static final void activate(Desktop desktop)
                           throws InterruptedException,
DesktopUnavailableException

Activates a thread to allow it access the given desktop synchronously. It causes the current thread to wait until the desktop is available to access, the desktop no longer exists, or some other thread interrupts this thread.

Alternative to activate(org.zkoss.zk.ui.Desktop)/deactivate(org.zkoss.zk.ui.Desktop), you could use schedule(org.zkoss.zk.ui.Desktop, org.zkoss.zk.ui.event.EventListener<T>, T) to execute a task under server push. schedule(org.zkoss.zk.ui.Desktop, org.zkoss.zk.ui.event.EventListener<T>, T) is asynchronous, while activate(org.zkoss.zk.ui.Desktop)/deactivate(org.zkoss.zk.ui.Desktop) is synchronous

Like schedule(org.zkoss.zk.ui.Desktop, org.zkoss.zk.ui.event.EventListener<T>, T), this method can be called anywhere, not limited to the event listener of the given desktop. It can be called even if there is no current execution.

The server-push is disabled by default. To use it, you have to enable it first with Desktop.enableServerPush(boolean) for the given desktop. Once enabled, you can use as many as server-push threads you like (for the desktop with the server-push feature enabled).

Before a thread, not running in the event listener of the given desktop, can access the desktop, you have to activate it first by activate(org.zkoss.zk.ui.Desktop). Once this method returns, the thread is activated and it, like an event listener of the given desktop, can manipulate the desktop directly.

A typical use pattern:

class MyWorkingThread extends Thread {
  public void run() {
    while (anything_to_publish) {
       //prepare something to publish
       //you can create new components and manipulate them before
       //activation, as long as they are not attached to the desktop

       Executions.activate(desktop);
       try {
         try {
           //activated
           //manipulate the components that are attached the desktop
         } finally {
           Executions.deactivate(desktop)
         }
       } catch (DesktopUnavailableException ex) {
         //clean up (since desktop is dead)
       }
   }
 }
}

Note: the access of components is sequentialized. That is, at most one thread is activated. All others, including the event listeners, have to wait until it is deactivated (i.e., until deactivate(org.zkoss.zk.ui.Desktop) is called). Thus, it is better to minimize the time remaining activated. A typical practice is to create new components and manipulate them before activated. Then, you have to only attach them after activated.

 Tree tree = new Tree();
 new Treechildren().setParent(tree); //initialize the tree
 Exections.activate(desktop);
 try {
   tree.setPage(page); //assume page is a page of desktop

Note: you don't need to invoke this method in the event listener since it is already activated when an event listen starts execution.

Note: When you call this method, ZK framework would require a lock on the thread. In the rare case that the framework, at the same time, is waiting on the release of another lock from your application, then a deadlock would result.

Throws:

InterruptedException - if it is interrupted by other thread

IllegalStateException - if the server push is not enabled.

DesktopUnavailableException - if the desktop is removed (when activating).

Since:

3.0.0

activate

public static final boolean activate(Desktop desktop,
 long timeout)
                              throws InterruptedException,
DesktopUnavailableException

Activates a thread to allow it access the given desktop synchronously, or until a certain amount of time has elapsed. It causes the current thread to wait until the desktop is available to access, the desktop no longer exists, some other thread interrupts this thread, or a certain amount of real time has elapsed.

Note: When you call this method, ZK framework would require a lock on the thread. In the rare case that the framework, at the same time, is waiting on the release of another lock from your application, then a deadlock would result.

Parameters:

timeout - the maximum time to wait in milliseconds. Ignored (i.e., never timeout) if non-positive.

Returns:

whether it is activated or it is timeout. The only reason it returns false is timeout.

Throws:

InterruptedException - if it is interrupted by other thread

DesktopUnavailableException - if the desktop is removed (when activating).

IllegalStateException - if the server push is not enabled for this desktop yet (Desktop.enableServerPush(boolean)).

Since:

3.0.0

See Also:

• activate(Desktop)
• deactivate(org.zkoss.zk.ui.Desktop)

deactivate

public static final void deactivate(Desktop desktop)

Deactivates a thread that has invoked activate(org.zkoss.zk.ui.Desktop) successfully.

Since:

3.0.0

See Also:

• activate(Desktop)
• activate(Desktop, long)