|
|
| (10 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| | {{ZKConfigurationReferencePageHeader}} | | {{ZKConfigurationReferencePageHeader}} |
| | | | |
| − | __TOC__
| + | Customizes ZK's default behavior. For example, |
| − | You might have multiple <tt>system-config</tt> elements in one <tt>zk.xml</tt>.
| |
| | | | |
| | <source lang="xml" > | | <source lang="xml" > |
| | <system-config> | | <system-config> |
| | <au-writer-class>my.AuWriter</au-writer-class> | | <au-writer-class>my.AuWriter</au-writer-class> |
| − | <cache-provider-class>my.CacheProvider | + | <cache-provider-class>my.CacheProvider</cache-provider-class> |
| − | </cache-provider-class>
| + | <crawlable>false</crawlable> |
| | <disable-event-thread /> | | <disable-event-thread /> |
| | <engine-class>my.UiEngine</engine-class> | | <engine-class>my.UiEngine</engine-class> |
| − | <failover-manager-class>my.FailoverManager | + | <failover-manager-class>my.FailoverManager</failover-manager-class> |
| − | </failover-manager-class> | + | <file-item-factory-class>my.DiskFileItemFactory</file-item-factory-class> |
| | + | <file-repository>/Users/foo/bar</file-repository> |
| | + | <file-size-threshold>1024</file-size-threshold> |
| | <id-generator-class>my.IdGenerator</id-generator-class> | | <id-generator-class>my.IdGenerator</id-generator-class> |
| | <max-spare-threads>100</max-spare-threads> | | <max-spare-threads>100</max-spare-threads> |
| Line 19: |
Line 20: |
| | <max-process-time>3000</max-process-time> | | <max-process-time>3000</max-process-time> |
| | <response-charset>UTF-8</response-charset> | | <response-charset>UTF-8</response-charset> |
| − | <session-cache-class>my.SessionCache | + | <session-cache-class>my.SessionCache</session-cache-class> |
| − | </session-cache-class>
| |
| | <upload-charset>UTF-8</upload-charset> | | <upload-charset>UTF-8</upload-charset> |
| | <upload-charset-finder-class>my.CharsetFinder | | <upload-charset-finder-class>my.CharsetFinder |
| | </upload-charset-finder-class> | | </upload-charset-finder-class> |
| | <ui-factory-class>my.UiFactory</ui-factory-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> | | <web-app-class>my.WebApp</web-app-class> |
| | </system-config> | | </system-config> |
| | </source> | | </source> |
| | | | |
| − | == The au-decoder-class Element ==
| + | {{ZKConfigurationReferenceHeadingToc}} |
| − | [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 <javadoc type="interface">org.zkoss.zk.au.AuDecoder</javadoc>.
| |
| − | | |
| − | 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.
| |
| − | | |
| − | #Implement <javadoc type="interface">org.zkoss.zk.au.AuDecoder</javadoc>
| |
| − | #Register it by specifying it with the <code>au-decoder-class</code> element in <code>WEB-INF/zk.xml</code>
| |
| − | #Override a JavaScript method called <javadoc directory="jsdoc" method="encode(int, zk.Event, zk.Desktop)">_global_.zAu</javadoc> to encode to the custom format
| |
| − | | |
| − | == The au-writer-class Element ==
| |
| − | [Default: <javadoc>org.zkoss.zk.au.http.HttpAuWriter</javadoc> for ZK CE and PE, or <javadoc>org.zkoss.zkmax.au.http.SmartAuWriter</javadoc> 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 <javadoc type="interface">org.zkoss.zk.au.AuWriter</javadoc> interface.
| |
| − | | |
| − | 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 ==
| |
| − | [Default: <javadoc>org.zkoss.zk.ui.impl.SessionDesktopCacheProvider</javadoc>]
| |
| − | | |
| − | It specifies which class used to implement the desktop cache. The class must have a default constructor (without any argument), and implement the <javadoc type="interface">org.zkoss.zk.ui.sys.DesktopCacheProvider</javadoc> 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.
| |
| − | | |
| − | | |
| − | {| border="1" | |
| − | ! <center>Class</center>
| |
| − | ! <center>Description</center>
| |
| − | | |
| − | |-
| |
| − | | 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, [http://www.bea.com/ 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 <tt>zk.xml</tt>. The parser must implement the <javadoc type="interface">org.zkoss.zk.ui.util.ConfigParser</javadoc> interface.
| |
| − | | |
| − | == Specifying crawlable content ==
| |
| − | [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.
| |
| − | <source lang="xml">
| |
| − | <system-config>
| |
| − | <crawlable>true</crawlable>
| |
| − | </system-config></source>
| |
| − | | |
| − | == 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.
| |
| − | | |
| − | 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%27s_Guide/ZK_in_Depth/Servlet_Thread_vs_Event_Thread | ZK Developer's Guide: Servlet Thread vs Event Thread]].
| |
| − | | |
| − | Enable the event thread only if the project does not need to integrate other frameworks (such as Spring), uses <javadoc>org.zkoss.zul.Messagebox</javadoc> and modal windows a lot, and does not have a lot of concurrent users.
| |
| − | | |
| − | == The engine-class Element ==
| |
| − | [Default: <javadoc>org.zkoss.zk.ui.impl.UiEngineImpl</javadoc>]
| |
| − | | |
| − | It specifies which class used to implement the UI Engine. The class must have a default constructor (without any argument), and implement the <javadoc type="interface">org.zkoss.zk.ui.sys.UiEngine</javadoc> 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 <javadoc type="interface">org.zkoss.zk.ui.sys.FailoverManager</javadoc> 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 <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 ==
| |
| − | [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 <javadoc type="interface">org.zkoss.zk.ui.sys.IdGenerator</javadoc> 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 <javadoc>org.zkoss.zk.ui.SuspendNotAllowedException</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 ==
| |
| − | [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: <javadoc>org.zkoss.zk.ui.http.SimpleSessionCache</javadoc>]
| |
| − | | |
| − | It specifies the session cache used to store ZK sessions. It must implement the <javadoc type="interface">org.zkoss.zk.ui.sys.SessionCache</javadoc> interface.
| |
| − | | |
| − | 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 ==
| |
| − | [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 <tt>upload-charset-finder-class</tt> 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 <javadoc type="interface">org.zkoss.zk.ui.util.CharsetFinder</javadoc> interface. Then, when a text file is uploaded, the <tt>getCharset</tt> 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 <tt>upload-charset</tt> element, see above.
| |
| − | | |
| − | == The ui-factory-class Element ==
| |
| − | [Default: <javadoc>org.zkoss.zk.ui.http.SimpleUiFactory</javadoc>]
| |
| − | | |
| − | 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 <javadoc type="interface">org.zkoss.zk.ui.sys.UiFactory</javadoc> 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.
| |
| − | | |
| − | | |
| − | {| border="1" | |
| − | ! <center>Class</center>
| |
| − | ! <center>Description</center>
| |
| − | | |
| − | |-
| |
| − | | 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 <javadoc type="interface">org.zkoss.web.servlet.http.Encodes.URLEncoder</javadoc><ref>The signature and functionality are enhanced, too.</ref>]
| |
| − | | |
| − | 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<ref>For example, the session ID is appended if the browser disabled the cookie.</ref> 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 <javadoc type="interface">org.zkoss.web.servlet.http.Encodes.URLEncoder</javadoc> interface, and specify it with the <tt>url-encoder-class</tt> element.
| |
| − | | |
| − | Notice that, unlike most other configuration, the <tt>url-encoder-class</tt> element affects all applications that share the same ZK libraries.
| |
| − | | |
| − | | |
| − | | |
| − | '''Notes'''
| |
| − | <references/>
| |
| − | | |
| − | == The web-app-class Element ==
| |
| − | [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.
| |
| − | | |
| − | ==Version History==
| |
| − | | |
| − | {| border='1px' | width="100%"
| |
| − | ! Version !! Date !! Content
| |
| − | |-
| |
| − | |
| |
| − | |
| |
| − | |
| |
| − | |}
| |
| − | | |
| | {{ZKConfigurationReferencePageFooter}} | | {{ZKConfigurationReferencePageFooter}} |