Package org.zkoss.zk.ui.event

Class 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

      Fields 
      Modifier and Type Field Description
      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

      Constructors 
      Constructor Description
      EventQueues()  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      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, 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, 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, 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, java.lang.String scope)
      Removes the event queue of the specified scope.
      static boolean remove​(java.lang.String name, Session sess)
      Removes the event queue of the specified session.
      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:

        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,
                                                     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