ZK Configuration Reference/zk.xml/The system-config Element

You might have multiple system-config elements in one zk.xml like following.

<system-config>
	<au-writer-class>my.AuWriter</au-writer-class>
	<cache-provider-class>my.CacheProvider</cache-provider-class>
	<crawlable>false</crawlable>
	<disable-event-thread />
	<engine-class>my.UiEngine</engine-class>
	<failover-manager-class>my.FailoverManager</failover-manager-class>
	<id-generator-class>my.IdGenerator</id-generator-class>
	<max-spare-threads>100</max-spare-threads>
	<max-suspended-threads>100</max-suspended-threads>
	<max-upload-size>5120</max-upload-size>
	<max-process-time>3000</max-process-time>
	<response-charset>UTF-8</response-charset>
	<session-cache-class>my.SessionCache</session-cache-class>
	<upload-charset>UTF-8</upload-charset>
	<upload-charset-finder-class>my.CharsetFinder
	</upload-charset-finder-class>
	<ui-factory-class>my.UiFactory</ui-factory-class>
	<url-encoder-class>my.URLEncoder</url-encoder-class>
	<web-app-class>my.WebApp</web-app-class>
</system-config>

The au-decoder-class Element

[Default: null (using the default JSON-based format)]
[since 5.0.4]

It specifies which class used to implement the AU decoder. The AU decoder is used to decode the AU requests. The class must implement AuDecoder.

By default, the AU request is sent in the JSON format. If you prefer to use another format, you could provide an implementation as follows.

1. Implement AuDecoder
2. Register it by specifying it with the au-decoder-class element in WEB-INF/zk.xml
3. Override a JavaScript method called zAu.encode(int, Event, Desktop) to encode to the custom format

The au-writer-class Element

[Default: HttpAuWriter for ZK CE and PE, or SmartAuWriter for ZK EE]

It specifies which class used to implement the AU writer. The AU writer is used to generate the output and send it to the client. The class must have a default constructor (without any argument), and implement the AuWriter interface.

There are two built-in implementations, HttpAuWriter and SmartAuWriter. The former one send the output the client after the requests are processed completely. On the other hand, the later one will send a partial output first if the processing is taking too long (half of the value specified in the resend-delay element). By sending the partial output, the client will know the server is still alive.

The cache-provider-class Element

[Default: SessionDesktopCacheProvider]

It specifies which class used to implement the desktop cache. The class must have a default constructor (without any argument), and implement the DesktopCacheProvider interface.

One instance of the cache provider is created and shared for each Web application, so you have to synchronize the access properly.

Available implementations are as follows.

Class	Description
org.zkoss.zk.ui.impl. SessionDesktopCacheProvider	It stores all desktops from the same session in one single cache. It is simple and fast, but not supporting clustering.
org.zkoss.zk.ui.impl. GlobalDesktopCacheProvider	It stores all desktops from the same Web application in one single cache. In other words, it doesn't count on session at all. It is useful because some Web server, e.g, BEA WebLogic, might be configured to use independent sessions for each request.

The config-parser-class Element

[Default: none]
[Since 5.0.0]

Specifies an application-specific parser to parse zk.xml. The parser must implement the ConfigParser interface.

The crawlable Element

[Default: false (disabled)]
[Since:5.0.0]

You are not able to specify whether content is crawlable, this works by generating tags within your content where content only exists in the form of Javascript. This allows your content to be crawled by Google and is similar to how the client-centric frameworks behave. However, there is a performance penalty so this option is disabled by default. You can enable it by using the example below.

Suggestion : If your website is used for external users, for better Search Engine Optimization (SEO) , turn this on.

<system-config>
   <crawlable>true</crawlable>
</system-config>

The disable-event-thread Element

[Default: false (enabled) for ZK 2.x and 3x, true (disabled) for ZK 5 ad later]

It specifies whether to disable the use of the event processing thread. If disabled, no event processing thread will be used at all. In other words, all events are processed in the same thread that serves HTTP request (so called Servlet thread) directly.

For better performance (and better compatible with other frameworks), it is recommended to disable the use of the event processing thread. For more information, please refer to ZK Developer's Reference.

Enable the event thread only if the project does not need to integrate other frameworks (such as Spring), uses Messagebox and modal windows a lot, and does not have a lot of concurrent users.

The engine-class Element

[Default: UiEngineImpl]

It specifies which class used to implement the UI Engine. The class must have a default constructor (without any argument), and implement the UiEngine interface.

One instance of the UI engine is created and shared for each Web application, so you have to synchronize the access properly.

The event-time-warning Element

 [Default: 600]
 [since 3.6.3]

It specifies the time, in seconds, to show a warning message if an event has been processinged longer than it.

The failover-manager-class Element

[Default: none]

It specifies which class used to handle the failover. It is called to recover a desktop, when ZK cannot locate a desktop. The class must have a default constructor (without any argument), and implement the FailoverManager interface.

In most cases, you don't need to provide any implementation. Rather, you can let Web servers to handle failover and clustering for you by specifying the SerializableUiFactory class in the ui-factory-class element as described above.

The id-generator-class Element

[Default: none]

It specifies which class used to generate UUID of page and components, and ID of desktops. The class must have a default constructor (without any argument), and implement the IdGenerator interface.

One instance of the ID generator is created and shared for each Web application, so you have to synchronize the access properly.

If no ID generator is specified, the default ID generation algorithm will be used.

The max-spare-threads Element

[Default: 100]

It specifies the maximal allowed number of the thread pool for queuing the idle event processing threads. ZK will reuse the idle event processing threads by keeping them in a thread pool. The number specified here then controls the maximal size of the pool.

A negative value indicates there is no limit. Zero means no pool at all.

The max-suspended-threads Element

[Default: -1 (no limit)]

It specifies the maximal allowed number of the suspended event processing threads. A negative value indicates there is no limit at all.

An instance of SuspendNotAllowedException is thrown, if an event processing thread is going to suspend and the number of suspended threads exceeds the number specified here. You can use the error-page element to control how to display this error, or catch the exception and handle it in a different way.'

The max-upload-size Element

[Default: 5120]

It specifies the maximal allowed size, in kilobytes, to upload a file from the client. A negative value indicates there is no limit.

The max-process-time Element

[Default: 3000]

It specifies the maximal allowed time to process events, in milliseconds. It must be positive. ZK will keep processing the requests until all requests are processed, or the maximal allowed time expires.

Note: This setting has no effect on AU requests. Rather, it controls the number of the requests caused by the client-polling server push. In other words, if there are multiple pending server-push based on the client-polling, ZK will handle them one-by-one until all are served or the time expires.

The response-charset Element

[Default: UTF-8]

It specifies the charset for the rendering result of a ZUML page. In other words, it is used to load the ZUML page by the ZK Loader (i.e., DHtmlLayoutServlet).

If you want to use the container's default value, you can specify an empty string as follows.

 <response-charset></response-charset>

The session-cache-class Element

[Default: SimpleSessionCache]

It specifies the session cache used to store ZK sessions. It must implement the SessionCache interface.

By default, SimpleSessionCache is used and it stores the ZK session in an attribute of the native session (i.e., HttpSession or PortletSession).

The upload-charset Element

[Default: UTF-8]

It specifies the charset (aka., encoding) for the uploaded text files if no charset is specified with the content type.

If the uploaded file is binary, there is no encoding issue at all.

Note: the upload-charset-finder-class element, see blow, has the higher priority.

The upload-charset-finder-class Element

[Default: null]

It specifies the finder that determines charset (aka.., encoding) for the uploaded text files if no charset is specified with the content type.

If the uploaded file is binary, there is no encoding issue at all.

The finder must implement the CharsetFinder interface. Then, when a text file is uploaded, the getCharset method is called and it can determines the encoding based on the content type and/or the content of the uploaded file.

Note: it has the higher priority than the upload-charset element, see above.

The ui-factory-class Element

[Default: SimpleUiFactory]

It specifies which class used to create desktops and pages, and to convert URL to a page definition. The class must have a default constructor (without any argument), and implement the UiFactory interface.

One instance of the UI factory is created and shared for each Web application, so you have to synchronize the access properly.

A common use is to load page definitions and other UI information from the database, rather than from the resources of the Web application.

In addition, you might use it to implement a controller in a MVC model, such that it creates the correct desktop based on the request URL.

Available implementations are as follows.

Class	Description
org.zkoss.zk.ui.http. SimpleUiFactory	The default UI factory. The sessions generated by this factory is not serializable
org.zkoss.zk.ui.http. SerializableUiFactory	The sessions generated by this factory is serializable. If you want to store sessions when the Web server is shutdown and restore them after it started, you can specify this implementation.

The url-encoder-class Element

[Default: none]
[Deprecated since 5.0; replaced with the library property called Encodes.URLEncoder]

It specifies the URL encoder to post-process the URL before sending to the client. By default, the URI generated is in the following format. Sometimes it is appended with the session ID.

/context-path/related-uri
/zkdemo/zkau/web/img/spacer.gif

In a sophisticated environment, you might want to modify a bit. Then, you can implement the Encodes.URLEncoder interface, and specify it with the url-encoder-class element.

Notice that, unlike most other configuration, the url-encoder-class element affects all applications that share the same ZK libraries.

Notes

The web-app-class Element

[Default: SimpleWebApp]

It specifies which class used to implement the Web application. The class must have a default constructor (without any argument), and implement both the WebApp and WebAppCtrl interfaces. Instead of implementing from scratch, you can extend it from the AbstractWebApp or SimpleWebApp classes.

Version History

Version	Date	Content