Package 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

    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:

      - 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