Subscribe to EventQueues"

From Documentation
m (replace tt with code (via JWB))
 
(18 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 
{{ZKDevelopersReferencePageHeader}}
 
{{ZKDevelopersReferencePageHeader}}
  
=Subscribe to EventQueues=
+
=Subscribe by <code>@Subscribe</code>=
You can subscribe a method (as if in an EventListener) to an [[ZK_Developer's_Reference/Event_Handling/Event_Queues | EventQueue]] by annotate it with <javadoc>org.zkoss.zk.ui.select.annotation.Subscribe</javadoc>. For example,
+
{{ZK EE}}
  
<source lang="java">
+
An method (as if in an EventListener) in [https://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/ui/select/SelectorComposer.html SelectorComposer] can subscribe to an [[ZK_Developer's_Reference/Event_Handling/Event_Queues | EventQueue]] by [https://www.zkoss.org/javadoc/latest/zk/org/zkoss/zkmax/ui/select/annotation/Subscribe.html @Subscribe]. For example,
 +
 
 +
<syntaxhighlight lang="java" highlight='3'>
 +
// in sender composer
 +
public void publish() {
 +
EventQueue<Event> eq = EventQueues.lookup("queue1", EventQueues.DESKTOP, true);
 +
eq.publish(new Event("onMyEvent", component, data));
 +
}
 +
</syntaxhighlight>
 +
 
 +
<syntaxhighlight lang='java' highlight='2'>
 +
// in receiver composer
 
@Subscribe("queue1")
 
@Subscribe("queue1")
public void method1(Event event) {
+
public void receive(Event event) {
 
// this method will be called when EventQueue "queue1" of Desktop scope is published
 
// this method will be called when EventQueue "queue1" of Desktop scope is published
 
Object data = event.getData();
 
Object data = event.getData();
 
Component target = event.getTarget();
 
Component target = event.getTarget();
 
}
 
}
public void publish() {
 
EventQueue<Event> eq = EventQueues.lookup("queue1", EventQueues.DESKTOP, true);
 
eq.publish(new Event("onMyEvent", component, data));
 
}
 
</source>
 
  
In the example above, when you publish an event in the EventQueue, the subscribed method will be called. It is a useful mechanism to communicate with other composers. See also
+
</syntaxhighlight>
 +
* Notice the queue name should match.
 +
* ZK executes both methods in a servlet thread, so if they execute a time-consuming operation, they will block users.
  
 +
In the example above, when you publish an event in the EventQueue, the subscribed method will be called. This is a useful mechanism to communicate among composers. See also <javadoc>org.zkoss.zk.ui.event.EventQueue</javadoc>.
  
&nbsp;
+
=EventQueue Scope=
==EventQueue Scope==
+
You can subscribe to EventQueue of different scopes.
You can subscribe to EventQueue of different scope.
 
  
<source lang="java">
+
<syntaxhighlight lang="java" highlight='1'>
 
@Subscribe(value = "queue2", scope = EventQueues.SESSION)
 
@Subscribe(value = "queue2", scope = EventQueues.SESSION)
 
public void method2(Event event) {
 
public void method2(Event event) {
Line 33: Line 41:
 
eq.publish(new Event("onMyEvent", component, data));
 
eq.publish(new Event("onMyEvent", component, data));
 
}
 
}
</source>
+
</syntaxhighlight>
  
 
Available scopes are: Desktop, Group, Session, Application. Note that Group scope requires ZK EE. See also <javadoc>org.zkoss.zk.ui.event.EventQueues</javadoc>.
 
Available scopes are: Desktop, Group, Session, Application. Note that Group scope requires ZK EE. See also <javadoc>org.zkoss.zk.ui.event.EventQueues</javadoc>.
  
  
&nbsp;
+
=Event Name=
==Subscriber Method Parameter==
+
{{versionSince| 7.0.3}} You can also listen to a specified event name
The method which subscribes to the EventQueue takes either no parameter, or one parameter of type Event.
+
<syntaxhighlight lang="java" highlight='1'>
 +
@Subscribe(value = "queue2", eventName = "event1")
 +
public void method2(Event event) {
 +
// this method will be called when EventQueue "queue2" of Session scope is published
 +
}
 +
public void publish() {
 +
EventQueue<Event> eq = EventQueues.lookup("queue2", EventQueues.DESKTOP, true);
 +
eq.publish(new Event("event1", component, data));
 +
}
 +
</syntaxhighlight>
 +
 
 +
 
 +
 
 +
=Subscriber Method Parameter=
 +
The method which subscribes to the EventQueue takes either no parameter or one parameter of a type Event.
  
 
<source lang="java">
 
<source lang="java">
Line 48: Line 70:
 
}
 
}
 
</source>
 
</source>
 +
 +
{{versionSince| 7.0.3}} ZK automatically maps event data into the method parameters in order.
 +
 +
<syntaxhighlight lang="java" highlight='2'>
 +
@Subscribe("queue3")
 +
public void method3(int i, String s) {
 +
// i will be 100, s will be "eventData"
 +
// ...
 +
}
 +
 +
public void publish() {
 +
EventQueue<Event> eq = EventQueues.lookup("queue3", EventQueues.DESKTOP, true);
 +
eq.publish(new Event("event1", component, new Object[]{100, "eventData"}));
 +
}
 +
</source>
 +
 +
If you put the event at the first one, it also works well.
 +
 +
<source lang="java">
 +
@Subscribe("queue3")
 +
public void method3(Event event, int i, String s) {
 +
// ...
 +
}
 +
</source>
 +
 +
To recap, we now have four ways to use a parameter:
 +
 +
* method()
 +
* method(Event event)
 +
* method(Event event, int d1, String d2, ....)
 +
* method(int d1, String d2, ...)
 +
 +
= Auto-Unsubscribed =
 +
<code>@Subscribe</code> will unsubscribe the subscribed event-queue automatically when the applied component (or its ancestor) of a composer is detached.
 +
 +
<!--https://tracker.zkoss.org/browse/ZK-1438-->
  
 
=Version History=
 
=Version History=
 
{{LastUpdated}}
 
{{LastUpdated}}
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-
Line 57: Line 115:
 
| April 2012
 
| April 2012
 
| @Subscribe was introduced.
 
| @Subscribe was introduced.
 +
|-
 +
| 7.0.3
 +
| June 2014
 +
| [http://tracker.zkoss.org/browse/ZK-2076 ZK-2076] Enhance Subscribe annotation to map java method by the event name and the parameter type in order
 
|}
 
|}
  
 
{{ZKDevelopersReferencePageFooter}}
 
{{ZKDevelopersReferencePageFooter}}

Latest revision as of 14:12, 12 January 2022


Subscribe to EventQueues


Subscribe by @Subscribe

  • Available for ZK:
  • http://www.zkoss.org/product/zkhttp://www.zkoss.org/whyzk/zkeeVersion ee.png

An method (as if in an EventListener) in SelectorComposer can subscribe to an EventQueue by @Subscribe. For example,

// in sender composer
public void publish() {
	EventQueue<Event> eq = EventQueues.lookup("queue1", EventQueues.DESKTOP, true);
	eq.publish(new Event("onMyEvent", component, data));
}
// in receiver composer
@Subscribe("queue1")
public void receive(Event event) {
	// this method will be called when EventQueue "queue1" of Desktop scope is published
	Object data = event.getData();
	Component target = event.getTarget();
}
  • Notice the queue name should match.
  • ZK executes both methods in a servlet thread, so if they execute a time-consuming operation, they will block users.

In the example above, when you publish an event in the EventQueue, the subscribed method will be called. This is a useful mechanism to communicate among composers. See also EventQueue.

EventQueue Scope

You can subscribe to EventQueue of different scopes.

@Subscribe(value = "queue2", scope = EventQueues.SESSION)
public void method2(Event event) {
	// this method will be called when EventQueue "queue2" of Session scope is published
}
public void publish() {
	EventQueue<Event> eq = EventQueues.lookup("queue2", EventQueues.SESSION, true);
	eq.publish(new Event("onMyEvent", component, data));
}

Available scopes are: Desktop, Group, Session, Application. Note that Group scope requires ZK EE. See also EventQueues.


Event Name

Since 7.0.3 You can also listen to a specified event name

@Subscribe(value = "queue2", eventName = "event1")
public void method2(Event event) {
	// this method will be called when EventQueue "queue2" of Session scope is published
}
public void publish() {
	EventQueue<Event> eq = EventQueues.lookup("queue2", EventQueues.DESKTOP, true);
	eq.publish(new Event("event1", component, data));
}


Subscriber Method Parameter

The method which subscribes to the EventQueue takes either no parameter or one parameter of a type Event.

@Subscribe("queue3")
public void method3() { // the event parameter can be omitted
	// ...
}

Since 7.0.3 ZK automatically maps event data into the method parameters in order.

<syntaxhighlight lang="java" highlight='2'> @Subscribe("queue3") public void method3(int i, String s) { // i will be 100, s will be "eventData" // ... }

public void publish() { EventQueue<Event> eq = EventQueues.lookup("queue3", EventQueues.DESKTOP, true); eq.publish(new Event("event1", component, new Object[]{100, "eventData"})); } </source>

If you put the event at the first one, it also works well.

@Subscribe("queue3")
public void method3(Event event, int i, String s) { 
	// ...
}

To recap, we now have four ways to use a parameter:

  • method()
  • method(Event event)
  • method(Event event, int d1, String d2, ....)
  • method(int d1, String d2, ...)

Auto-Unsubscribed

@Subscribe will unsubscribe the subscribed event-queue automatically when the applied component (or its ancestor) of a composer is detached.


Version History

Last Update : 2022/01/12


Version Date Content
6.0.1 April 2012 @Subscribe was introduced.
7.0.3 June 2014 ZK-2076 Enhance Subscribe annotation to map java method by the event name and the parameter type in order


Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.