org.zkoss.zk.ui.event
Class EventQueues

java.lang.Object
  org.zkoss.zk.ui.event.EventQueues

public class EventQueues
extends java.lang.Object

Utilities to access the event queue.

Customization:

The implementation of EventQueue and even the scope are customizable. To customize, specify the name of a class implementing EventQueueProvider in the library property called "org.zkoss.zk.ui.event.EventQueueProvider.class". For example, you can use JMS to extend the queue to be able to communicate with applications running in different JVM.

Since:

5.0.0

Author:

tomyeh

Field Summary

static java.lang.String	APPLICATION Represents the event queue in the application scope.
static java.lang.String	DESKTOP Represents the event queue in the desktop scope.
static java.lang.String	GROUP Represents a group of desktops that belongs to the same browser.
static java.lang.String	SESSION Represents the event queue in the sessions cope.

Constructor Summary

EventQueues()

Method Summary

static boolean	exists(java.lang.String name) Tests if the specified event queue has been created in the current desktop.
static boolean	exists(java.lang.String name, java.lang.String scope) Tests if the specified event queue has been created.
static <T extends Event> EventQueue<T>	lookup(java.lang.String name) Returns the desktop-level event queue with the specified name in the current desktop, or if no such event queue, create one.
static <T extends Event> EventQueue<T>	lookup(java.lang.String name, boolean autoCreate) Returns the desktop-level event queue with the specified name in the current desktop.
static <T extends Event> EventQueue<T>	lookup(java.lang.String name, Session sess, boolean autoCreate) Returns the event queue with the specified name in the give session (i.e., the session scope).
static <T extends Event> EventQueue<T>	lookup(java.lang.String name, java.lang.String scope, boolean autoCreate) Returns the event queue with the specified name in the specified scope.
static <T extends Event> EventQueue<T>	lookup(java.lang.String name, WebApp wapp, boolean autoCreate) Returns the event queue with the specified name in the give application (i.e., the application scope).
static boolean	remove(java.lang.String name) Removes the event queue.
static boolean	remove(java.lang.String name, Session sess) Removes the event queue of the specified session.
static boolean	remove(java.lang.String name, java.lang.String scope) Removes the event queue of the specified scope.
static boolean	remove(java.lang.String name, WebApp wapp) Removes the event queue of the specified application.

Methods inherited from class java.lang.Object

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

Field Detail

DESKTOP

public static final java.lang.String DESKTOP

Represents the event queue in the desktop scope. In other words, the events published to this kind of queues can be passed around only in the same desktop.

See Also:

Constant Field Values

GROUP

public static final java.lang.String GROUP

Represents a group of desktops that belongs to the same browser. It is formed if iframe or frameset is used.

Unlike APPLICATION and SESSION, it does NOT require the server push, so there is no overhead. However, it cannot communicate with desktops that belongs to other top browser windows/tabs. Since there is no way to detect two desktops (of the same session) belongs to the same top browser window, the developer has to make sure of it by himself.

Some portal container, such as Liferay, also forms a group of desktops (they all belongs to the same browser window). Notice that org.zkoss.zkmax.zul.Portallayout is a component and it won't cause additional desktop to be created, unless iframe is used as the content.

Note: this feature requires ZK EE.

Since:

5.0.4

See Also:

Constant Field Values

APPLICATION

public static final java.lang.String APPLICATION

Represents the event queue in the application scope. In other words, the events published to this kind of queues can be passed around to any desktops of the same application.

Notice that this feature will enable the server push (ServerPush.

Note: according to the ServletContext javadoc - http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContext.html the application scope cannot support under cluster environment. When information needs to be shared between servlets running in a distributed environment, the information should be placed into a session scope.

See Also:

Constant Field Values

SESSION

public static final java.lang.String SESSION

Represents the event queue in the sessions cope. In other words, the events published to this kind of queues can be passed around to any desktops of the same session.

Notice that this feature will enable the server push (ServerPush.

See Also:

Constant Field Values

Constructor Detail

EventQueues

public EventQueues()

Method Detail

lookup

public static <T extends Event> EventQueue<T> lookup(java.lang.String name,
                                                     java.lang.String scope,
                                                     boolean autoCreate)

Returns the event queue with the specified name in the specified scope.

There are several kinds of event scopes: DESKTOP, GROUP, SESSION, and APPLICATION.

If the DESKTOP scope is specified, the event queue is associated with the desktop of the current execution. And, the event queue is gone if the desktop is removed, or removed manually by remove(java.lang.String).

If the SESSION or GROUP scope is specified, the event queue is associated with the current session. And, the event queue is gone if the session is invalidated, or removed manually by remove(java.lang.String).

If the APPLICATION scope is specified, the event queue is associated with the application, and remains until the application stops or removed manually by remove(java.lang.String).

When an execution subscribes an event queue of SESSION or APPLICATION, the server push is enabled automatically. On the other hand, DESKTOP and GROUP does NOT require the server push -- they use the AU requests for communication.

Note:

• This method can be called only in an activated execution, i.e., Executions.getCurrent() not null. If you want to use it without an execution, please use lookup(String, Session, boolean) or lookup(String, WebApp, boolean) instead (depending on your scope).

Parameters:

name - the queue name.

scope - the scope of the event queue. Currently, it supports DESKTOP, GROUP, SESSION, and APPLICATION. Note: GROUP requires ZK EE.

autoCreate - whether to create the event queue if not found.

Returns:

the event queue with the associated name, or null if not found and autoCreate is false

Throws:

java.lang.IllegalStateException - if not in an activated execution

java.lang.UnsupportedOperationException - if the scope is not supported

See Also:

lookup(String, Session, boolean), lookup(String, WebApp, boolean)

lookup

public static <T extends Event> EventQueue<T> lookup(java.lang.String name,
                                                     Session sess,
                                                     boolean autoCreate)

Returns the event queue with the specified name in the give session (i.e., the session scope).

Unlike lookup(String, String, boolean), this method can be called without an activated execution.

Parameters:

sess - the session that the event queue is located (i.e., the session scope)

Since:

5.0.2

See Also:

lookup(String, String, boolean), lookup(String, WebApp, boolean)

lookup

public static <T extends Event> EventQueue<T> lookup(java.lang.String name,
                                                     WebApp wapp,
                                                     boolean autoCreate)

Returns the event queue with the specified name in the give application (i.e., the application scope).

Unlike lookup(String, String, boolean), this method can be called without an activated execution.

Parameters:

wapp - the Web application that the event queue is located (i.e., the application scope)

Since:

5.0.2

See Also:

lookup(String, String, boolean), lookup(String, Session, boolean)

lookup

public static <T extends Event> EventQueue<T> lookup(java.lang.String name,
                                                     boolean autoCreate)

Returns the desktop-level event queue with the specified name in the current desktop. It is a shortcut of lookup(name, DESKTOP, autoCreate).

lookup

public static <T extends Event> EventQueue<T> lookup(java.lang.String name)

Returns the desktop-level event queue with the specified name in the current desktop, or if no such event queue, create one. It is a shortcut of lookup(name, DESKTOP, true).

exists

public static boolean exists(java.lang.String name,
                             java.lang.String scope)

Tests if the specified event queue has been created.

exists

public static boolean exists(java.lang.String name)

Tests if the specified event queue has been created in the current desktop. It is a shortcut of exists(name, DESKTOP)

remove

public static boolean remove(java.lang.String name)

Removes the event queue. It is the same as remove(name, DESKTOP).

Parameters:

name - the queue name.

Returns:

true if it is removed successfully

remove

public static boolean remove(java.lang.String name,
                             java.lang.String scope)

Removes the event queue of the specified scope.

Parameters:

name - the queue name.

scope - the scope of the event queue. Currently, it supports DESKTOP, GROUP, SESSION, and APPLICATION. Note: GROUP requires ZK EE.

Returns:

true if it is removed successfully

remove

public static boolean remove(java.lang.String name,
                             Session sess)

Removes the event queue of the specified session.

Unlike remove(String, String), this method can be called without an activated execution.

Parameters:

name - the queue name.

sess - the session that the event queue is located (i.e., the session scope)

Returns:

true if it is removed successfully

Since:

5.0.4

remove

public static boolean remove(java.lang.String name,
                             WebApp wapp)

Removes the event queue of the specified application.

Unlike remove(String, String), this method can be called without an activated execution.

Parameters:

name - the queue name.

wapp - the Web application that the event queue is located (i.e., the application scope)

Returns:

true if it is removed successfully

Since:

5.0.4