Configuration"

From Documentation
Line 1: Line 1:
 
{{ZKDevelopersReferencePageHeader}}
 
{{ZKDevelopersReferencePageHeader}}
  
ZK have two implementations: <javadoc>org.zkoss.zk.ui.impl.PollingServerPush</javadoc> and <javadoc>org.zkoss.zkmax.ui.comet.CometServerPush</javadoc>. As their name suggest, they implement the Client-Polling and Comet (aka., long-polling) server pushes.
+
ZK have three implementations: <javadoc>org.zkoss.zk.ui.impl.PollingServerPush</javadoc>, <javadoc>org.zkoss.zkex.ui.comet.CometServerPush</javadoc> and 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 (Servlet 3 Asynchronous Processing-based Comet) server pushes.
  
 
For '''ZK5''', the default implementation depends on which ZK edition you use. ZK CE and PE will use <javadoc>org.zkoss.zk.ui.impl.PollingServerPush</javadoc> ZK EE will use <javadoc>org.zkoss.zkmax.ui.comet.CometServerPush</javadoc>. You configure ZK to use the one you prefer, even to use a custom server push.
 
For '''ZK5''', the default implementation depends on which ZK edition you use. ZK CE and PE will use <javadoc>org.zkoss.zk.ui.impl.PollingServerPush</javadoc> ZK EE will use <javadoc>org.zkoss.zkmax.ui.comet.CometServerPush</javadoc>. You configure ZK to use the one you prefer, even to use a custom server push.

Revision as of 03:32, 20 April 2012

ZK have three implementations: PollingServerPush, CometServerPush and 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.

For ZK5, the default implementation depends on which ZK edition you use. ZK CE and PE will use PollingServerPush ZK EE will use CometServerPush. You configure ZK to use the one you prefer, even to use a custom server push.

For ZK6, the CometServerPush is available in ZK PE, while ZK EE supports Servlet 3 Asynchronous Processing-based Comet.

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.

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));

Error Handling

The configuration of the errors is handled by [[ZK Configuration Reference/zk.xml/The client-config Element/The error-reload Element|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.

Version History

Last Update : 2012/04/20


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.



Last Update : 2012/04/20

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