Configuration
From ZKDesktop
|
Overview
The following configuration files need to either be edited or created before you can run the ZK Desktop. If you don't know what something means or how it works, just use the values presented below.
Tomcat Configuration
The configuration data for Tomcat is stored in the web.xml file located in the WEB-INF directory. Below is a sample configuration file:
<?xml version="1.0" encoding="UTF-8"?>
<web-app id="WebApp_ID"
version="2.4"
xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://java.sun.com/xml/ns/j2ee http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
<display-name>Your Site Name Here</display-name>
<!-- ZK -->
<listener>
<description>Used to cleanup when a session is destroyed</description>
<display-name>ZK Session Cleaner</display-name>
<listener-class>org.zkoss.zk.ui.http.HttpSessionListener</listener-class>
</listener>
<servlet>
<description>ZK loader for ZUML pages</description>
<servlet-name>zkLoader</servlet-name>
<servlet-class>org.zkoss.zk.ui.http.DHtmlLayoutServlet</servlet-class>
<!-- Must. Specifies URI of the update engine (DHtmlUpdateServlet).
It must be the same as <url-pattern> for the update engine.
-->
<init-param>
<param-name>update-uri</param-name>
<param-value>/zkau</param-value>
</init-param>
<init-param>
<param-name>compress</param-name>
<param-value>true</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>zkLoader</servlet-name>
<url-pattern>*.zul</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>zkLoader</servlet-name>
<url-pattern>*.zhtml</url-pattern>
</servlet-mapping>
<servlet>
<description>The asynchronous update engine for ZK</description>
<servlet-name>auEngine</servlet-name>
<servlet-class>org.zkoss.zk.au.http.DHtmlUpdateServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>auEngine</servlet-name>
<url-pattern>/zkau/*</url-pattern>
</servlet-mapping>
<!-- End of ZK -->
<!-- ZK Desktop -->
<listener>
<listener-class>zkdesktop.ZKDStatic</listener-class>
</listener>
<filter>
<filter-name>Block XML Files</filter-name>
<filter-class>zkdesktop.BlockFileFilter</filter-class>
<init-param>
<param-name>message</param-name>
<param-value>Sorry, you are not allowed to view this page.</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>Block XML Files</filter-name>
<url-pattern>*.xml</url-pattern>
</filter-mapping>
<!-- End of ZK Desktop -->
<session-config>
<session-timeout>99999</session-timeout> <!-- Crazy Not Gonna Happen Timeout. Don't change. -->
</session-config>
<welcome-file-list>
<welcome-file>index.zul</welcome-file>
</welcome-file-list>
</web-app>
ZK Configuration
The configuration data for the ZK "AJAX without JavaScript" toolkit is stored in the zk.xml file located in the WEB-INF directory.
Below is a sample configuration file:
<zk> <!-- ZK Desktop --> <listener> <listener-class>zkdesktop.ZKDStatic</listener-class> </listener> <session-config> <session-timeout>120</session-timeout> <!-- Safety Net Timeout. Always 2 minutes. --> <timer-keep-alive>true</timer-keep-alive> </session-config> <system-config> <cache-provider-class>org.zkoss.zk.ui.impl.SessionDesktopCacheProvider</cache-provider-class> </system-config> </zk>
Zero Kelvin Desktop Configuration
Configuration data for the Zero Kelvin Desktop application is stored in the zkdesktop.xml file located in the WEB-INF directory on the web server.
A sample configuration file looks like this:
<zkdesktop>
<keymaster>zkdesktop.KeyMasterSample</keymaster>
<persistence>zkdesktop.PersistenceSample</persistence>
<menu>
<startvisible>true</startvisible>
<containchildren>false</containchildren>
</menu>
<warn>50</warn> <!-- Display Timeout Warning After x Minutes -->
<timeout>60</timeout> <!-- Session Timeout in Minutes -->
<timeoutpage>/timeout.html</timeoutpage>
<sqlserver>
<enabled>true</enabled>
<name>zkdesktop</name>
<port>9001</port>
</sqlserver>
<database>
<driver>org.hsqldb.jdbcDriver</driver>
<connection>jdbc:hsqldb:hsql://%COMPUTERNAME%/zkdesktop;shutdown=true</connection>
<user>sa</user>
<password></password>
</database>
<thirdparty>
<jaeger>
<mydatabase><![CDATA[jdbc:mysql://%COMPUTERNAME%/zkdesktop?user=zkuser&password=zkpass]]></mydatabase>
</jaeger>
</thirdparty>
</zkdesktop>
The following configuration options are available:
- keymaster - the full classname of the Pluggable Security Module used to authenticate access to applications on the site.
- persistence - the full classname of the Pluggable Persistence Module used to store user data for applications on the site.
- menu/startvisible - determines the initial visibility of the main application menu. Visibility of this menu can be changed via IPC messages.
- menu/containchildren - determines if child windows in the menu application can be dragged and positioned outside their parent window or not. Set to 'false' to allow children on the desktop.
- warn - Number of minutes until an idle user is warned about timing out.
- timeout - Number of minutes until an idle user times out.
- timeoutpage - URL of the page to display when a user times out.
- sqlserver - section for configuring the embedded SQL server - see below.
- database - section for configuring the connection to the embedded SQL server - see below.
- thirdparty - the thirdparty group provides a location for other developers to add their own configuration data to the XML file. In this case, the developer jaeger has added a mydatabase setting.
Notice that in the <mydatabase> line that we've used a Windows environment variable name in the configuration value. When this value is loaded, %COMPUTERNAME% will be replaced with the value of the COMPUTERNAME environment variable. This allows you to define environment-specific configuration data within XML files. Very helpful when deploying across multiple computers! You may use the name of any environment variable available on your system - just enclose it in percent signs.
SQLServer Section
The ZK Desktop includes an embedded SQL server (see the HSQLDB link for details). While you are still free to use your own database server or other back-end for the Pluggable Security Module and Pluggable Persistence Module, using the internal database allows you to run the ZK Desktop without depending on any other database software.
The available configuration options for the embedded SQL server are:
- enabled - determines if the embedded server is enabled or not. You may wish to disable it to run multiple instances of ZKD against one database. See below.
- name - the name of the database to serve. "zkdesktop" is the recommended value.
- port - the TCP/IP port to answer requests on. 9001 is the default.
If you enable the internal SQL server, the zkdesktop.dbinit script will be run against it once during the initial startup of the ZK Desktop. You can extend this script to perform additional database setup tasks.
WARNING! The default configuration allows anyone to connect to the embedded database. It's highly recommended that you block the database server port with your firewall from the outside world. You may also wish to read the HSQLDB documentation for details on configuring passwords.
Database Section
In addition to configuring the internal SQL server, you may also specify how the ZK Desktop connects to the embedded server. While this may seem redundant, it allows multiple instances of the ZK Desktop to share a single database or to do away with the embedded database altogether.
The available connection options are:
- driver - the JDBC driver class to use to connect to the database.
- connection - the connection string to use when connecting.
- user - the name of the user to connect to the database.
- password - the password for the user.
As mentioned above, you can run multiple instances of the ZK Desktop on different machines and share a single embedded database. This allows you to share configuration and persistence data across multiple machines. To use this feature, do the following:
- Enable the embedded SQL server on the "master" instance of the ZK Desktop.
- Disable the embedded SQL server on all other instances.
- Change the default connection string to connect to the master instance.
