ZK Configuration"

From Documentation
m ((via JWB))
(20 intermediate revisions by 4 users not shown)
Line 3: Line 3:
 
=Turn on Serializable UI Factory=
 
=Turn on Serializable UI Factory=
  
−
[Required]
+
{{Notice| text=Required}}
  
−
To use ZK in a clustering environment, you have to use the serializable UI factory. It could be done by specifying the following statement in <tt>WEB-INF/zk.xml</tt>:
+
To use ZK in a clustering environment, you have to use the serializable UI factory. It could be done by specifying the following statement in <code>WEB-INF/zk.xml</code>:
  
 
<source lang="xml">
 
<source lang="xml">
−
<zk>
 
 
<system-config>
 
<system-config>
 
<ui-factory-class>org.zkoss.zk.ui.http.SerializableUiFactory</ui-factory-class>
 
<ui-factory-class>org.zkoss.zk.ui.http.SerializableUiFactory</ui-factory-class>
 
</system-config>
 
</system-config>
−
</zk>
 
 
</source>
 
</source>
  
−
<javadoc>org.zkoss.zk.ui.http.SerializableUiFactory</javadoc> is the UI factory that will instantiate serializable sessions such that the sessions, components, pages and desktops will be serialized when a session is about to deactivate.
+
<javadoc>org.zkoss.zk.ui.http.SerializableUiFactory</javadoc> is the UI factory that will instantiate serializable sessions such that the sessions, components, pages, and desktops will be serialized when a session is about to deactivate.
  
−
=Turn on ClusterSessionPath for WebLogic and GAE=
+
=Additional settings for various servers=
−
[Required if WebLogic and GAE][No need for other servers]
+
Please refer to the following links for detailed settings.
−
[Since 5.0.8]
+
*[[ZK_Installation_Guide/Setting_up_Servers/Tomcat_Cluster|Tomcat Cluster]]
−
 
+
*[[ZK_Installation_Guide/Setting_up_Servers/WebLogic_Cluster|WebLogic Cluster]]
−
WebLogic clustering server and GAE (Google App Engine) minimize the synchronization of the session states by assuming nothing has changed, if no session attribute has been modified in a HTTP request. Thus, you have to specify the following configuration in <tt>WEB-INF/zk.xml</tt> to enforce the server to synchronize the states for each Ajax request.
+
*[[ZK_Installation_Guide/Setting_up_Servers/Google_App_Engine|Google App Engine]]
−
 
+
*[[ZK_Installation_Guide/Setting_up_Servers/JBoss_Cluster|JBoss Cluster]]
−
<source lang="xml">
 
−
<zk>
 
−
<listener>
 
−
<listener-class>org.zkoss.zkplus.cluster.ClusterSessionPatch</listener-class>
 
−
</listener>
 
−
</zk>
 
−
</source>
 
−
 
 
−
<blockquote>
 
−
----
 
−
Under the hub: <javadoc>org.zkoss.zkplus.cluster.ClusterSessionPatch</javadoc> is an <javadoc type="interface">org.zkoss.zk.util.ExecutionCleanup</javadoc> listener that updates an session attribute holding <javadoc type="interface">org.zkoss.zk.ui.Session</javadoc> for each request.
 
−
</blockquote>
 
−
 
 
−
=Additional settings for JBoss=
 
−
[Required if JBoss]
 
−
*According to JBoss' guide, additional settings are required if you are using JBoss server for clustering. Add the following settings in <tt>WEB-INF/web.xml</tt> to tell JBoss that you wish to cluster your web app.
 
−
<source lang="xml">
 
−
<?xml version="1.0"?>
 
−
<web-app  xmlns="http://java.sun.com/xml/ns/javaee"
 
−
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 
−
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
 
−
    version="2.5">
 
−
   
 
−
    <distributable/>
 
−
 
 
−
</web-app>
 
−
</source>
 
−
*Create <tt>jboss-web.xml</tt> file under WEB-INF folder if ''fileupload''' component is used in your app.
 
−
<source lang="xml">
 
−
<jboss-web>
 
−
    <context-root>warFileName</context-root> <!-- context-root should be the same with war file name -->   
 
−
    <replication-config>
 
−
        <cache-name>standard-session-cache</cache-name>
 
−
        <replication-trigger>SET_AND_GET</replication-trigger>
 
−
        <replication-granularity>SESSION</replication-granularity>
 
−
        <replication-field-batch-mode>true</replication-field-batch-mode>
 
−
        <use-jk>true</use-jk>
 
−
        <max-unreplicated-interval>30</max-unreplicated-interval>
 
−
        <snapshot-mode>INSTANT</snapshot-mode>
 
−
        <snapshot-interval>1000</snapshot-interval>
 
−
    </replication-config>
 
−
    <max-active-sessions>5</max-active-sessions>
 
−
    <passivation-config>
 
−
        <use-session-passivation>true</use-session-passivation>
 
−
        <passivation-min-idle-time>60</passivation-min-idle-time>
 
−
        <passivation-max-idle-time>600</passivation-max-idle-time>
 
−
    </passivation-config>
 
−
</jboss-web>
 
−
</source>
 
  
 
=Turn on Log=
 
=Turn on Log=
Line 77: Line 26:
 
  [Optional]
 
  [Optional]
  
−
If an attribute or a listener is not serializable, ZK will skip it, i.e., not to serialize it (similar to how a Servlet container serializes the attributes of sessions). It is sometimes hard to know what are ignored, since it is common for a developer to forget to declare a value or a listener as serializable.
+
If an attribute or a listener is not serializable, ZK will skip it, i.e., not serialize it (similar to how a Servlet container serializes the attributes of sessions). It is sometimes hard to know what is ignored since it is common for a developer to forget to declare a value or a listener as serializable.
−
 
 
−
To detect this problem, you could turn on the logger for <tt>org.zkoss.io.serializable</tt> to the DEBUG level<ref>Available in 5.0.7</ref>. The logger is [http://download.oracle.com/javase/6/docs/api/java/util/logging/Logger.html the standard logger]. You could consult the configuration of the Web server you use. Or, you could run the following statement when your application starts<ref>It can be done by use of the<javadoc type="interface">org.zkoss.zk.ui.util.WebAppInit</javadoc> listener. For more information, please refer to [[ZK Developer's Reference/Customization|the Customization section]].</ref>.
 
−
 
 
−
<source lang="java">
 
−
org.zkoss.util.logging.Log.lookup("org.zkoss.io.serializable").setLevel("DEBUG");
 
−
</source>
 
  
−
<blockquote>
+
To detect this problem, you can turn on the logger for <code>org.zkoss.io.serializable</code> to the DEBUG level ({{versionSince| 5.0.7}}). Please read [[ZK%20Developer's%20Reference/Supporting%20Utilities/Logger | Logger]] for details.
−
----
 
−
<references/>
 
−
</blockquote>
 
  
 
=Disable the Use of zscript=
 
=Disable the Use of zscript=
  
 
  [Optional]
 
  [Optional]
−
[since 5.0.8]
+
{{versionSince|5.0.8}}
  
−
The interpreter (BeanShell) does not work well under the clustering environment, since the serializationis not stable. Thus, it is suggested to disable the use of zscript with the following statement. It is optional, but, by disabling, it is easy to prevent any possible use.
+
The interpreter (BeanShell) does not work well under the clustering environment. Since the serialization is not stable, zscript cannot be used in a clustering environment.
 +
To avoid accidental or unintended use it is recommended to disable zscript in your ZK application with the following configuration (in zk.xml):
  
 
<source lang="xml">
 
<source lang="xml">
Line 107: Line 48:
  
 
==Event Processing Thread==
 
==Event Processing Thread==
−
Do not enable the event processing thread. The event processing thread might be suspended, while the (suspended) thread cannot be migrated from one machine to another.
+
Do not enable [[ZK_Developer%27s_Reference/UI_Patterns/Event_Threads| the event processing thread]]. The event processing thread might be suspended, while the (suspended) thread cannot be migrated from one machine to another.
  
 
It is disabled by default. For more information, please refer to the [[ZK Developer's Reference/UI Patterns/Event Threads|Event Threads]] section.
 
It is disabled by default. For more information, please refer to the [[ZK Developer's Reference/UI Patterns/Event Threads|Event Threads]] section.
Line 114: Line 55:
 
Do not use <javadoc>org.zkoss.zk.ui.impl.GlobalDesktopCacheProvider</javadoc> (global desktop cache). The global desktop cache is stored in the servlet context, while only the data stored in sessions are migrated when failover takes place.
 
Do not use <javadoc>org.zkoss.zk.ui.impl.GlobalDesktopCacheProvider</javadoc> (global desktop cache). The global desktop cache is stored in the servlet context, while only the data stored in sessions are migrated when failover takes place.
  
−
The desktop desktop cache is ''not'' used by default<ref>Rather, the default is <javadoc>org.zkoss.zk.ui.impl.SessionDesktopCacheProvider</javadoc>.</ref>. Just make sure you don't configure it wrong.
+
The default is <javadoc>org.zkoss.zk.ui.impl.SessionDesktopCacheProvider</javadoc> instead of  desktop-scoped desktop cache. Just make sure you don't configure it wrong.
  
−
<blockquote>
+
=Version History=
−
----
 
−
<references/>
 
−
</blockquote>
 
  
−
=Version History=
+
{| class='wikitable' | width="100%"
−
{{LastUpdated}}
 
−
{| border='1px' | width="100%"
 
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-
 
| 5.0.7
 
| 5.0.7
 
| April 2011
 
| April 2011
−
| The log called <tt>org.zkoss.io.serializable</tt> was introduced.
+
| The log called <code>org.zkoss.io.serializable</code> was introduced.
 
|-
 
|-
 
| 5.0.8
 
| 5.0.8
 
| June 2011
 
| June 2011
−
| The listener called <tt>org.zkoss.zkplus.cluster.ClusterSessionPatch</tt> was introduced.
+
| The listener called <code>org.zkoss.zkplus.cluster.ClusterSessionPatch</code> was introduced.
 
|}
 
|}
  
 
{{ZKDevelopersReferencePageFooter}}
 
{{ZKDevelopersReferencePageFooter}}

Revision as of 07:32, 8 July 2022


DocumentationZK Developer's ReferenceClusteringZK Configuration
ZK Configuration


Turn on Serializable UI Factory

Icon info.png Notice: Required

To use ZK in a clustering environment, you have to use the serializable UI factory. It could be done by specifying the following statement in WEB-INF/zk.xml: 

	<system-config>
		<ui-factory-class>org.zkoss.zk.ui.http.SerializableUiFactory</ui-factory-class>
	</system-config>

SerializableUiFactory is the UI factory that will instantiate serializable sessions such that the sessions, components, pages, and desktops will be serialized when a session is about to deactivate.

Additional settings for various servers

Please refer to the following links for detailed settings.

Turn on Log

[Optional]

If an attribute or a listener is not serializable, ZK will skip it, i.e., not serialize it (similar to how a Servlet container serializes the attributes of sessions). It is sometimes hard to know what is ignored since it is common for a developer to forget to declare a value or a listener as serializable.

To detect this problem, you can turn on the logger for org.zkoss.io.serializable to the DEBUG level (Since 5.0.7). Please read Logger for details.

Disable the Use of zscript

[Optional]

Since 5.0.8

The interpreter (BeanShell) does not work well under the clustering environment. Since the serialization is not stable, zscript cannot be used in a clustering environment. To avoid accidental or unintended use it is recommended to disable zscript in your ZK application with the following configuration (in zk.xml): 

<system-config>
	<disable-zscript>true</disable-zscript>
</system-config>

Configuration Not Allowed

Here are a list of configuration that can not be used in the clustering environment. They are disabled by default. However, it is worth to double check if any of your members enables it accidentally.

Event Processing Thread

Do not enable the event processing thread. The event processing thread might be suspended, while the (suspended) thread cannot be migrated from one machine to another.

It is disabled by default. For more information, please refer to the Event Threads section.

Global Desktop Cache

Do not use GlobalDesktopCacheProvider (global desktop cache). The global desktop cache is stored in the servlet context, while only the data stored in sessions are migrated when failover takes place.

The default is SessionDesktopCacheProvider instead of desktop-scoped desktop cache. Just make sure you don't configure it wrong.

Version History

Version Date Content
5.0.7 April 2011 The log called org.zkoss.io.serializable was introduced.
5.0.8 June 2011 The listener called org.zkoss.zkplus.cluster.ClusterSessionPatch was introduced.



Last Update : 2022/07/08

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


Retrieved from "https://www.zkoss.org/_w/index.php?title=ZK_Developer%27s_Reference/Clustering/ZK_Configuration&oldid=54652"