The system-config Element"

From Documentation
m
m
Line 30: Line 30:
 
</source>
 
</source>
  
=== The au-writer-class Element ===
+
== The au-writer-class Element ==
 
  [Default: <javadoc>org.zkoss.zk.au.http.HttpAuWriter</javadoc> for standard and professional editions, or <javadoc>org.zkoss.zkmax.au.http.SmartAuWriter</javadoc> for enterprise edition]
 
  [Default: <javadoc>org.zkoss.zk.au.http.HttpAuWriter</javadoc> for standard and professional editions, or <javadoc>org.zkoss.zkmax.au.http.SmartAuWriter</javadoc> for enterprise edition]
  
Line 37: Line 37:
 
There are two built-in implementations, <tt>HttpAuWriter</tt> and <tt>SmartAuWriter</tt>. 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 <tt>resend-delay</tt> element). By sending the partial output, the client will know the server is still alive.
 
There are two built-in implementations, <tt>HttpAuWriter</tt> and <tt>SmartAuWriter</tt>. 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 <tt>resend-delay</tt> element). By sending the partial output, the client will know the server is still alive.
  
=== The cache-provider-class Element ===
+
== The cache-provider-class Element ==
 
  [Default: <javadoc>org.zkoss.zk.ui.impl.SessionDesktopCacheProvider</javadoc>]
 
  [Default: <javadoc>org.zkoss.zk.ui.impl.SessionDesktopCacheProvider</javadoc>]
  
Line 69: Line 69:
 
<references/>
 
<references/>
  
=== The config-parser-class Element ===
+
== The config-parser-class Element ==
 
  [Default: none]
 
  [Default: none]
 
  [Since 5.0.0]
 
  [Since 5.0.0]
Line 75: Line 75:
 
Specifies an application-specific parser to parse <tt>zk.xml</tt>. The parser must implement the <javadoc type="interface">org.zkoss.zk.ui.util.ConfigParser</javadoc> interface.
 
Specifies an application-specific parser to parse <tt>zk.xml</tt>. The parser must implement the <javadoc type="interface">org.zkoss.zk.ui.util.ConfigParser</javadoc> interface.
  
=== The disable-event-thread Element ===
+
== The disable-event-thread Element ==
 
  [Default: false (enabled) for ZK 2.x and 3x, true (disabled) for ZK 5 ad later]
 
  [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.
 
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 ===
+
== The engine-class Element ==
 
  [Default: <javadoc>org.zkoss.zk.ui.impl.UiEngineImpl</javadoc>]
 
  [Default: <javadoc>org.zkoss.zk.ui.impl.UiEngineImpl</javadoc>]
  
Line 87: Line 87:
 
One instance of the UI engine is created and shared for each Web application, so you have to synchronize the access properly.
 
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 ===
+
== The failover-manager-class Element ==
 
  [Default: ''none'']
 
  [Default: ''none'']
  
Line 94: Line 94:
 
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 <javadoc>org.zkoss.zk.ui.http.SerializableUiFactory</javadoc> class in the <tt>ui-factory-class</tt> element as described above.
 
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 <javadoc>org.zkoss.zk.ui.http.SerializableUiFactory</javadoc> class in the <tt>ui-factory-class</tt> element as described above.
  
=== The id-generator-class Element ===
+
== The id-generator-class Element ==
 
  [Default: ''none'']
 
  [Default: ''none'']
  
Line 103: Line 103:
 
If no ID generator is specified, the default ID generation algorithm will be used.
 
If no ID generator is specified, the default ID generation algorithm will be used.
  
=== The max-spare-threads Element ===
+
== The max-spare-threads Element ==
 
  [Default: 100]
 
  [Default: 100]
  
Line 110: Line 110:
 
A negative value indicates there is no limit. Zero means no pool at all.
 
A negative value indicates there is no limit. Zero means no pool at all.
  
=== The max-suspended-threads Element ===
+
== The max-suspended-threads Element ==
 
  [Default: -1 ''(no limit)'']
 
  [Default: -1 ''(no limit)'']
  
Line 117: Line 117:
 
'''An instance of <javadoc>org.zkoss.zk.ui.TooManySuspendedException</javadoc> 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 <tt>error-page</tt> element to control how to display this error, or catch the exception and handle it in a different way.'''
 
'''An instance of <javadoc>org.zkoss.zk.ui.TooManySuspendedException</javadoc> 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 <tt>error-page</tt> element to control how to display this error, or catch the exception and handle it in a different way.'''
  
=== The max-upload-size Element ===
+
== The max-upload-size Element ==
 
  [Default: 5120]
 
  [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.
 
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 ===
+
== The max-process-time Element ==
 
  [Default: 3000]
 
  [Default: 3000]
  
Line 129: Line 129:
 
'''Note''': Since 3.0.1, this setting has no obvious effect on Ajax devices. Ajax devices send the requests synchronously.
 
'''Note''': Since 3.0.1, this setting has no obvious effect on Ajax devices. Ajax devices send the requests synchronously.
  
=== The response-charset Element ===
+
== The response-charset Element ==
 
  [Default: UTF-8]
 
  [Default: UTF-8]
  
Line 138: Line 138:
 
   <response-charset></response-charset>
 
   <response-charset></response-charset>
  
=== The session-cache-class Element ===
+
== The session-cache-class Element ==
 
  [Default: <javadoc>org.zkoss.zk.ui.http.SimpleSessionCache</javadoc>]
 
  [Default: <javadoc>org.zkoss.zk.ui.http.SimpleSessionCache</javadoc>]
  
Line 145: Line 145:
 
By default, <javadoc>org.zkoss.zk.ui.http.SimpleSessionCache</javadoc> is used and it stores the ZK session in an attribute of the native session (i.e., <tt>HttpSession</tt> or <tt>PortletSession</tt>).
 
By default, <javadoc>org.zkoss.zk.ui.http.SimpleSessionCache</javadoc> is used and it stores the ZK session in an attribute of the native session (i.e., <tt>HttpSession</tt> or <tt>PortletSession</tt>).
  
=== The upload-charset Element ===
+
== The upload-charset Element ==
 
  [Default: UTF-8]
 
  [Default: UTF-8]
  
Line 154: Line 154:
 
Note: the <tt>upload-charset-finder-class</tt> element, see blow, has the higher priority.
 
Note: the <tt>upload-charset-finder-class</tt> element, see blow, has the higher priority.
  
=== The upload-charset-finder-class Element ===
+
== The upload-charset-finder-class Element ==
 
  [Default: null]
 
  [Default: null]
  
Line 165: Line 165:
 
'''Note:''' it has the higher priority than the <tt>upload-charset</tt> element, see above.
 
'''Note:''' it has the higher priority than the <tt>upload-charset</tt> element, see above.
  
=== The ui-factory-class Element ===
+
== The ui-factory-class Element ==
 
  [Default: <javadoc>org.zkoss.zk.ui.http.SimpleUiFactory</javadoc>]
 
  [Default: <javadoc>org.zkoss.zk.ui.http.SimpleUiFactory</javadoc>]
  
Line 195: Line 195:
 
|}
 
|}
  
=== The url-encoder-class Element ===
+
== The url-encoder-class Element ==
 
  [Default: ''none'']
 
  [Default: ''none'']
 
  [Deprecated since 5.0; replaced with the library property called <javadoc type="interface">org.zkoss.web.servlet.http.Encodes.URLEncoder</javadoc><ref>The signature and functionality are enhanced, too.</ref>]
 
  [Deprecated since 5.0; replaced with the library property called <javadoc type="interface">org.zkoss.web.servlet.http.Encodes.URLEncoder</javadoc><ref>The signature and functionality are enhanced, too.</ref>]
Line 213: Line 213:
 
<references/>
 
<references/>
  
=== The web-app-class Element ===
+
== The web-app-class Element ==
 
  [Default: <javadoc>org.zkoss.zk.ui.http.SimpleWebApp</javadoc>]
 
  [Default: <javadoc>org.zkoss.zk.ui.http.SimpleWebApp</javadoc>]
  
 
It specifies which class used to implement the Web application. The class must have a default constructor (without any argument), and implement both the <javadoc type="interface">org.zkoss.zk.ui.WebApp</javadoc> and <javadoc type="interface">org.zkoss.zk.ui.sys.WebAppCtrl</javadoc> interfaces. Instead of implementing from scratch, you can extend it from the <javadoc>org.zkoss.zk.ui.impl.AbstractWebApp</javadoc> or <javadoc>org.zkoss.zk.ui.http.SimpleWebApp</javadoc> classes.
 
It specifies which class used to implement the Web application. The class must have a default constructor (without any argument), and implement both the <javadoc type="interface">org.zkoss.zk.ui.WebApp</javadoc> and <javadoc type="interface">org.zkoss.zk.ui.sys.WebAppCtrl</javadoc> interfaces. Instead of implementing from scratch, you can extend it from the <javadoc>org.zkoss.zk.ui.impl.AbstractWebApp</javadoc> or <javadoc>org.zkoss.zk.ui.http.SimpleWebApp</javadoc> classes.
 +
 +
==Version History==
  
 
{{ZKConfigurationReferencePageFooter}}
 
{{ZKConfigurationReferencePageFooter}}

Revision as of 08:10, 13 July 2010


The system-config Element


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: HttpAuWriter for standard and professional editions, or 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 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[1], might be configured to use independent sessions for each request.


Notes

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

  1. The signature and functionality are enhanced, too.
  2. For example, the session ID is appended if the browser disabled the cookie.

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

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