The system-config Element"

Revision as of 02:41, 9 July 2010

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

<system-config>
	<au-writer-class>my.AuWriter</au-writer-class>
	<cache-provider-class>my.CacheProvider
	</cache-provider-class>
	<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-writer-class Element

[Default: org.zkoss.zk.au.http.HttpAuWriter for standard and professional editions, or org.zkoss.zkmax.au.http.SmartAuWriter for enterprise edition]

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 org.zkoss.zk.au.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: org.zkoss.zk.ui.impl.SessionDesktopCacheProvider]

It specifies which class used to implement the desktop cache. The class must have a default constructor (without any argument), and implement the org.zkoss.zk.ui.sys.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^[1], might be configured to use independent sessions for each request.

Notes

↑ http://www.bea.com

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 org.zkoss.zk.ui.util.ConfigParser interface.

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 Servlet thread directly.

The engine-class Element

[Default: org.zkoss.zk.ui.impl.UiEngineImpl]

It specifies which class used to implement the UI Engine. The class must have a default constructor (without any argument), and implement the org.zkoss.zk.ui.sys.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 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 org.zkoss.zk.ui.sys.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 org.zkoss.zk.ui.http.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 org.zkoss.zk.ui.sys.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 org.zkoss.zk.ui.TooManySuspendedException 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 sent from the client until all requests are processed, or the maximal allowed time expires.

Note: Since 3.0.1, this setting has no obvious effect on Ajax devices. Ajax devices send the requests synchronously.

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: org.zkoss.zk.ui.http.SimpleSessionCache]

It specifies the session cache used to store ZK sessions. It must implement the org.zkoss.zk.ui.sys.SessionCache interface.

By default, org.zkoss.zk.ui.http.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 org.zkoss.zk.ui.util.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: org.zkoss.zk.ui.http.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 org.zkoss.zk.ui.sys.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 org.zkoss.web.servlet.http.URLEncoder^[1]]

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^[2] 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 org.zkoss.web.servlet.http.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.