Package org.zkoss.zk.ui.event

Class EventQueues

java.lang.Object
org.zkoss.zk.ui.event.EventQueues
public class EventQueues extends 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

    Fields
    Modifier and Type
    Field
    Description
    static final String
    APPLICATION
    Represents the event queue in the application scope.
    static final String
    DESKTOP
    Represents the event queue in the desktop scope.
    static final String
    GROUP
    Represents a group of desktops that belongs to the same browser.
    static final String
    SESSION
    Represents the event queue in the sessions cope.

  • Constructor Summary

    Constructors
    Constructor
    Description
    EventQueues()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean
    exists(String name)
    Tests if the specified event queue has been created in the current desktop.
    static boolean
    exists(String name, String scope)
    Tests if the specified event queue has been created.
    static <T extends Event>
    EventQueue<T>
    lookup(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(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(String name, String scope, boolean autoCreate)
    Returns the event queue with the specified name in the specified scope.
    static <T extends Event>
    EventQueue<T>
    lookup(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(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(String name)
    Removes the event queue.
    static boolean
    remove(String name, String scope)
    Removes the event queue of the specified scope.
    static boolean
    remove(String name, Session sess)
    Removes the event queue of the specified session.
    static boolean
    remove(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 Details

    • DESKTOP

      public static final 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:

    • GROUP

      public static final 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:

    • APPLICATION

      public static final 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/jakarta.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:

    • SESSION

      public static final 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:

  • Constructor Details

    • EventQueues

      public EventQueues()

  • Method Details

    • lookup

      public static <T extends Event> EventQueue<T> lookup(String name, 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:

      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:
      IllegalStateException - if not in an activated execution
      UnsupportedOperationException - if the scope is not supported
      See Also:

    • lookup

      public static <T extends Event> EventQueue<T> lookup(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

      public static <T extends Event> EventQueue<T> lookup(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

      public static <T extends Event> EventQueue<T> lookup(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(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(String name, String scope)
      Tests if the specified event queue has been created.

    • exists

      public static boolean exists(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(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(String name, 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(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(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