Configuration"

From Documentation
m
 
(46 intermediate revisions by 10 users not shown)
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.
+
__TOC__
  
The default implementation depends on which ZK edition you use. If ZK CE and PE, <javadoc>org.zkoss.zk.ui.impl.PollingServerPush</javadoc> will be used. If ZK EE, <javadoc>org.zkoss.zkmax.ui.comet.CometServerPush</javadoc> will be used. You configure ZK to use the one you prefer, even to use a custom server 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 names 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.
 +
 
 +
The default implementation depends on which ZK edition you use:
 +
 
 +
{| class="wikitable"
 +
! ZK Edition
 +
! Technology
 +
! ZK Implementation
 +
|-
 +
| CE
 +
| Client Polling
 +
| <javadoc>org.zkoss.zk.ui.impl.PollingServerPush</javadoc>
 +
|-
 +
| PE
 +
| Comet Server Push
 +
| <javadoc>org.zkoss.zkex.ui.comet.CometServerPush</javadoc>
 +
|-
 +
| EE
 +
| Servlet 3 Comet
 +
| <javadoc>org.zkoss.zkmax.ui.comet.CometServerPush</javadoc>
 +
|}
 +
 
 +
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 use <javadoc>org.zkoss.zk.ui.impl.PollingServerPush</javadoc>, and ZK 5 EE uses <javadoc>org.zkoss.zkmax.ui.comet.CometServerPush</javadoc>.
  
 
=Choose an Implementation=
 
=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.
+
Client-polling is based on a timer that peeks the server continuously to see if any data is 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==
 
==Page-level Configuration==
You could configure a particular ZK page to use a particular implementation by use of <javadoc method="enableServerPush(org.zkoss.zk.ui.sys.ServerPush)" type="interface">org.zkoss.zk.ui.sys.DesktopCtrl</javadoc>. For example,
+
You could configure a particular ZK page to use a particular implementation by the use of <javadoc method="enableServerPush(org.zkoss.zk.ui.sys.ServerPush)" type="interface">org.zkoss.zk.ui.sys.DesktopCtrl</javadoc>. For example,
  
 
<source lang="java">
 
<source lang="java">
Line 19: Line 43:
 
==Application-level Configuration==
 
==Application-level Configuration==
  
If you would like to change the default server push for the whole application, you could use the [[ZK Configuration Reference/zk.xml/The device-config Element#The_server-push-class_Element|the server-push-class element]] as follows.
+
If you would like to change the default server push for the whole application, you could use [[ZK Configuration Reference/zk.xml/The device-config Element/The_server-push-class_Element|the server-push-class element]] as follows.
  
 
<source lang="xml">
 
<source lang="xml">
 
<device-config>
 
<device-config>
 
     <device-type>ajax</device-type>
 
     <device-type>ajax</device-type>
     <server-push-class>org.zkoss.zkex.ui.impl.PollingServerPush</server-push-class>
+
     <server-push-class>org.zkoss.zk.ui.impl.PollingServerPush</server-push-class>
 
</device-config>
 
</device-config>
 
</source>
 
</source>
Line 30: Line 54:
 
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>.
  
=Customize Client-Polling=
+
=Client-Polling Configuration=
<javadoc>org.zkoss.zk.ui.impl.PollingServerPush</javadoc> 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.
+
The client-polling server push is implemented with an implicit timer at the client. The interval of the timer depends on the loading of the server. For example, the interval becomes longer if the time to get a response has become longer. <javadoc>org.zkoss.zk.ui.impl.PollingServerPush</javadoc> 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
+
== PollingServerPush.delay.min ==
*:The minimal delay to send the second polling request (unit: milliseconds). Default: 1000.
+
The minimal delay to send the second polling request (unit: milliseconds).  
*PollingServerPush.delay.max
+
Default: 1000.
*: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 multiplies the delay factor. For example, if the last request took 1 second to process, then the client polling will be delayed for <code>1 x factor</code> seconds. Default: 5.
 
*:The larger the factor is, the longer delay it tends to be.</dd>
 
  
It could be configured in <code>WEB-INF/xml</code> by use of [[ZK Configuration Reference/zk.xml/The preference Element|the preference element]] as follows.
+
==  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 multiplied by the delay factor. For example, if the last request took 1 second to process, then the client polling will be delayed for <code>1 x factor</code> seconds. Default: 5.
 +
* The larger the factor, the longer the delay tends to be.
 +
 
 +
It could be configured in <code>WEB-INF/zk.xml</code> by use of [[ZK Configuration Reference/zk.xml/The preference Element|the preference element]] as follows.
  
 
<source lang="xml">
 
<source lang="xml">
Line 68: Line 96:
 
</source>
 
</source>
  
In additions, you could specify them in the constructor: <javadoc method="PollingServerPush(int, int, int)">org.zkoss.zk.ui.impl.PollingServerPush</javadoc>.
+
In additions, you could specify them in the constructor: <javadoc method="PollingServerPush(int, int, int)">org.zkoss.zk.ui.impl.PollingServerPush</javadoc>. For example,
 +
 
 +
<source lang="java">
 +
((DesktopCtrl)desktop).enableServerPush(
 +
    new org.zkoss.zk.ui.impl.PollingServerPush(2000,10000,3));
 +
</source>
 +
 
 +
= Comet Server Push Config =
 +
{{versionSince|8.0.2}}
 +
The comet server push is implemented with a pre-established and 'virtual' permanent connection. It is like sending a taxi to the server, and waiting in the server until there is data to send back. Meanwhile, the client-polling server push is like sending a taxi periodically to the server, and leaving immediately if no data is available.
 +
 
 +
<javadoc>org.zkoss.zkex.ui.comet.CometServerPush</javadoc> comes with its own configuration parameters such as retry delay, retry count, and ajax timeout.
 +
 
 +
Configure these parameters by using [[ZK Configuration Reference/zk.xml/The preference Element|the preference element]] in your <code>WEB-INF/zk.xml</code> e.g.
 +
 
 +
<source lang="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>
 +
</source>
 +
 
 +
== CometServerPush.retry.delay ==
 +
The minimum time delay to send the next comet request retry (unit: milliseconds).
 +
Default: 5000.
 +
==  CometServerPush.retry.count ==
 +
The maximum retry counts if a comet request fails, -1 means keep retry forever (unit: count).
 +
Default: 10.
 +
==  CometServerPush.ajax.timeout ==
 +
The amount of time a comet request will wait for a server response until it aborts. (unit: milliseconds).
 +
Default: varies, [https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/timeout depending on browsers]
 +
 
 +
= 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 <code>WEB-INF/zk.xml</code>. The markup below demonstrates an example of catching an error of the server push:
 +
 
 +
<source lang="xml" highlight="3">
 +
<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>
 +
</source>
 +
 
 +
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 <code>server-push</code>.
 +
 
 +
= "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 is returned, there will be one "dummy" request sent to retrieve server update.
 +
 
 +
= WebSocketServerPush =
 +
{{versionSince|8.5.0}}
 +
 
 +
Since ZK 8.5.0, the WebSocket based Server Push <javadoc>org.zkoss.zkmax.au.websocket.WebSocketServerPush</javadoc> is provided. When WebSocket connection is enabled, this will be used as default, other configuration specifying which Server Push to use will be ignored.
  
 
=Version History=
 
=Version History=
{{LastUpdated}}
+
 
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-
| &nbsp;
+
| 6.0.0
| &nbsp;
+
| Feb 2012
| &nbsp;
+
| The CometServerPush is available in ZK PE, while ZK EE supports Servlet 3 Asynchronous Processing-based Comet.
 
|}
 
|}
  
 
{{ZKDevelopersReferencePageFooter}}
 
{{ZKDevelopersReferencePageFooter}}

Latest revision as of 04:18, 1 February 2024

Since ZK 6, in addition to PollingServerPush and CometServerPush, ZK provides a third Server Push implementation - Asynchronous Processing CometServerPush. As their names 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:

ZK Edition Technology ZK Implementation
CE Client Polling PollingServerPush
PE Comet Server Push CometServerPush
EE Servlet 3 Comet CometServerPush

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 use 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 is 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 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.

Client-Polling Configuration

The client-polling server push is implemented with an implicit timer at the client. The interval of the timer depends on the loading of the server. For example, the interval becomes longer if the time to get a response has become longer. 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 multiplied by 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, the longer the delay 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));

Comet Server Push Config

Since 8.0.2 The comet server push is implemented with a pre-established and 'virtual' permanent connection. It is like sending a taxi to the server, and waiting in the server until there is data to send back. Meanwhile, the client-polling server push is like sending a taxi periodically to the server, and leaving immediately if no data is available.

CometServerPush comes with its own configuration parameters such as retry delay, retry count, and ajax timeout.

Configure these parameters by using the preference element in your WEB-INF/zk.xml e.g.

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

CometServerPush.retry.delay

The minimum time delay to send the next comet request retry (unit: milliseconds).

Default: 5000.

CometServerPush.retry.count

The maximum retry counts if a comet request fails, -1 means keep retry forever (unit: count).

Default: 10.

CometServerPush.ajax.timeout

The amount of time a comet request will wait for a server response until it aborts. (unit: milliseconds).

Default: varies, depending on browsers

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 is returned, there will be one "dummy" request sent to retrieve server update.

WebSocketServerPush

Since 8.5.0

Since ZK 8.5.0, the WebSocket based Server Push WebSocketServerPush is provided. When WebSocket connection is enabled, this will be used as default, other configuration specifying which Server Push to use will be ignored.

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.



Last Update : 2024/02/01

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