Configuration"
Line 1: | Line 1: | ||
{{ZKDevelopersReferencePageHeader}} | {{ZKDevelopersReferencePageHeader}} | ||
+ | |||
+ | {{Template:UnderConstruction}} | ||
Since ZK 6, in addition to <javadoc>org.zkoss.zk.ui.impl.PollingServerPush</javadoc> and <javadoc>org.zkoss.zkex.ui.comet.CometServerPush</javadoc> ZK provides a third Server Push implementation - Asynchronous Processing <javadoc>org.zkoss.zkmax.ui.comet.CometServerPush</javadoc>. As their name suggest, they implement the Client-Polling, Comet (aka., long-polling) and Servlet 3 Comet ([http://books.zkoss.org/wiki/Small_Talks/2012/February/New_Features_of_ZK_6#ZK_Comet_supports_Servlet_3_Asynchronous_Processing Servlet 3 Asynchronous Processing-based Comet]) server pushes. Client-Polling is available in all editions, Comet Server Push is available in ZK PE and EE, while ZK EE supports Servlet 3 Comet Push. | Since ZK 6, in addition to <javadoc>org.zkoss.zk.ui.impl.PollingServerPush</javadoc> and <javadoc>org.zkoss.zkex.ui.comet.CometServerPush</javadoc> ZK provides a third Server Push implementation - Asynchronous Processing <javadoc>org.zkoss.zkmax.ui.comet.CometServerPush</javadoc>. As their name suggest, they implement the Client-Polling, Comet (aka., long-polling) and Servlet 3 Comet ([http://books.zkoss.org/wiki/Small_Talks/2012/February/New_Features_of_ZK_6#ZK_Comet_supports_Servlet_3_Asynchronous_Processing Servlet 3 Asynchronous Processing-based Comet]) server pushes. Client-Polling is available in all editions, Comet Server Push is available in ZK PE and EE, while ZK EE supports Servlet 3 Comet Push. | ||
Line 31: | Line 33: | ||
where you could specify any implementation that implements <javadoc type="interface">org.zkoss.zk.ui.sys.ServerPush</javadoc>. | where you could specify any implementation that implements <javadoc type="interface">org.zkoss.zk.ui.sys.ServerPush</javadoc>. | ||
− | |||
− | |||
=Customized Client-Polling= | =Customized Client-Polling= |
Revision as of 08:09, 23 May 2016
Since ZK 6, in addition to PollingServerPush and CometServerPush ZK provides a third Server Push implementation - Asynchronous Processing CometServerPush. As their name suggest, they implement the Client-Polling, Comet (aka., long-polling) and Servlet 3 Comet (Servlet 3 Asynchronous Processing-based Comet) server pushes. Client-Polling is available in all editions, Comet Server Push is available in ZK PE and EE, while ZK EE supports Servlet 3 Comet Push.
The default implementation depends on which ZK edition you use. By default CE uses Client Polling, PE uses Comet Server Push, EE uses Servlet 3 Comet. You can also configure ZK to use the one you prefer, or even use a custom server push.
Note that Comet Server Push is available in ZK 5 EE only. By default, ZK 5 CE and ZK 5 PE uses PollingServerPush and ZK 5 EE uses CometServerPush.
Choose an Implementation
Client-polling is based on a timer that peeks the server continuously to see if any data to be pushed to the client, while Comet establishes a permanent connection for instant push. Client-polling will introduce more traffic due to the continuous peeks, but Comet will consume the network connections that a server allows.
Page-level Configuration
You could configure a particular ZK page to use a particular implementation by the use of DesktopCtrl.enableServerPush(ServerPush). For example,
((DesktopCtrl)desktop).enableServerPush(
new org.zkoss.zk.ui.impl.PollingServerPush(2000,5000,-1));
Application-level Configuration
If you would like to change the default server push for the whole application, you could use the the server-push-class element as follows.
<device-config>
<device-type>ajax</device-type>
<server-push-class>org.zkoss.zk.ui.impl.PollingServerPush</server-push-class>
</device-config>
where you could specify any implementation that implements ServerPush.
Customized Client-Polling
PollingServerPush uses a timer to peek if the server has any data to push back. The period between two peeks is determined by a few factors.
- PollingServerPush.delay.min
- The minimal delay to send the second polling request (unit: milliseconds). Default: 1000.
- PollingServerPush.delay.max
- The maximal delay to send the second polling request (unit: milliseconds). Default: 15000.
- PollingServerPush.delay.factor
- The delay factor. The real delay is the processing time that multiplies the delay factor. For example, if the last request took 1 second to process, then the client polling will be delayed for
1 x factor
seconds. Default: 5. - The larger the factor is, the longer delay it tends to be.
- The delay factor. The real delay is the processing time that multiplies the delay factor. For example, if the last request took 1 second to process, then the client polling will be delayed for
It could be configured in WEB-INF/zk.xml
by use of the preference element as follows.
<preference>
<name>PollingServerPush.delay.min</name>
<value>3000</value>
</preference>
<preference>
<name>PollingServerPush.delay.max</name>
<value>10000</value>
</preference>
<preference>
<name>PollingServerPush.delay.factor</name>
<value>5</value>
</preference>
<!-- JavaScript code to start the server push; rarely required
<preference>
<name>PollingServerPush.start</name>
<value></value>
</preference>
<preference>
<name>PollingServerPush.stop</name>
<value></value>
</preference>
-->
In additions, you could specify them in the constructor: PollingServerPush.PollingServerPush(int, int, int). For example,
((DesktopCtrl)desktop).enableServerPush(
new org.zkoss.zk.ui.impl.PollingServerPush(2000,10000,3));
Comet Server Push Config
[since 8.0.2]
CometServerPush now comes with its own configuration parameters such as retry delay, retry count, and ajax timeout.
- CometServerPush.retry.delay
- The minimum time delay to send the next comet request retry (unit: milliseconds). Default: 5000.
- CometServerPush.retry.count
- The maximum retry count if a comet requests failed (unit: count). Default: 10.
- CometServerPush.ajax.timeout
- The amount of time a comet request will wait for a server response until it abort. This is a global setting that will affect all your ajax requests, including ZK AU requests, please use with caution (unit: milliseconds). Default: varies, depending on browser
Configure these parameters by using the preference element in your WEB-INF/zk.xml
<preference>
<name>CometServerPush.retry.delay</name>
<value>3000</value><!-- 3 seconds delay between each retry-->
</preference>
<preference>
<name>CometServerPush.retry.count</name>
<value>3</value><!-- 3 tries for each request -->
</preference>
<preference>
<name>CometServerPush.ajax.timeout</name>
<value>180000</value><!-- 3 minutes -->
</preference>
Error Handling
The configuration of the errors is handled by the client-reload element, specified in WEB-INF/zk.xml
. The markup below demonstrates an example of catching an error of the server push:
<error-reload>
<device-type>ajax</device-type>
<connection-type>server-push</connection-type>
<error-code>410</error-code>
<reload-uri>/login.zul</reload-uri>
</error-reload>
where the connection-type element specifies through which channel the requests are sent. By default it is the AU channel in which Ajax requests are sent by widgets running at the client. If you would like to specify the error page for server-push then connection-type must be set to server-push
.
"dummy" Requests
When using ServerPush the client engine will send "dummy"-requests (without extra payload) to the /zkau servlet to pull queued server side updates.
Those requests look similar to this:
dtid=z_m06&cmd_0=dummy&opt_0=i
In the case of PollingServerPush there will be one of these requests per configured interval, sometimes causing a firewall to give a false alert.
In the case of CometServerPush, after a long polling comet request returned, there will be one "dummy" request sent to retrieve server update.
Version History
Version | Date | Content |
---|---|---|
6.0.0 | Feb 2012 | The CometServerPush is available in ZK PE, while ZK EE supports Servlet 3 Asynchronous Processing-based Comet. |