|
|
| Line 1: |
Line 1: |
| | {{ZKConfigurationReferencePageHeader}} | | {{ZKConfigurationReferencePageHeader}} |
| | | | |
| − | __TOC__
| |
| | The allowed child elements include <tt>session-timeout</tt> and <tt>max-desktops-per-session</tt>. You might have multiple <tt>session-config</tt> elements in one <tt>zk.xml</tt>. | | The allowed child elements include <tt>session-timeout</tt> and <tt>max-desktops-per-session</tt>. You might have multiple <tt>session-config</tt> elements in one <tt>zk.xml</tt>. |
| | | | |
| Line 14: |
Line 13: |
| | </source> | | </source> |
| | | | |
| − | == The automatic-timeout Element ==
| + | {{ZKConfigurationReferenceHeadingToc}} |
| − | [Optional]
| |
| − | [Since 3.6.3]
| |
| − | [Default: false]
| |
| − | | |
| − | It specifies whether to automatically redirect to the timeout URI.
| |
| − | | |
| − | If false, it means a page will be redirected to the timeout URI, when the use takes some action after timeout.
| |
| − | | |
| − | In other words, nothing happens (no redirect) if the user does nothing on the page.
| |
| − | | |
| − | If it is set to true, it is redirected as soon as timeout, no matter the user takes any action.
| |
| − | | |
| − | Notice that this setting is applied only to the specified device ([[#The device-type Element|<device-type>]]), so remember to specify the correct device. For example,
| |
| − | | |
| − | <source lang="xml">
| |
| − | <session-config>
| |
| − | <device-type>ajax</device-type>
| |
| − | <automatic-timeout/> <!-- the same as <automatic-timeout>true</automatic-timeout> -->
| |
| − | <timeout-uri>/timeout.zul</timeout-uri>
| |
| − | </session-config>
| |
| − | </source>
| |
| − | | |
| − | <blockquote>
| |
| − | === Page-level Automatic Timeout ===
| |
| − | | |
| − | If you want to specify whether to automatically timeout for particular pages, you can use [[ZUML Reference/ZUML/Processing Instructions/page#automaticTimeout | the page directive]].
| |
| − | | |
| − | Moreover, it is better to turn off the automatic timeout for the timeout page you want to redirect to (if the page is a ZUML page). For example,
| |
| − | | |
| − | <source lang="xml">
| |
| − | <!-- my timeout page -->
| |
| − | <?page automaticTimeout="false"?>
| |
| − | ...
| |
| − | </source>
| |
| − | </blockquote>
| |
| − | | |
| − | == The device-type Element ==
| |
| − | [Optional]
| |
| − | [Since 3.6.3]
| |
| − | [Default: ajax]
| |
| − | | |
| − | It specifies the device type that <tt><timeout-uri></tt> and <tt><automatic-timeout></tt> are applied to. By default, it is <tt>ajax</tt>. If you want to specify the timeout URI for mobile device, use <tt>mil</tt>.
| |
| − | | |
| − | Notice that only <tt><timeout-uri></tt> and <tt><automatic-timeout></tt> depend on this. Others, such as <session-timeout>, are applied to all devices, regardless what is specified here.
| |
| − | | |
| − | == The max-desktops-per-session Element ==
| |
| − | [Default: 15]
| |
| − | | |
| − | It specifies the maximal allowed number of desktops per session. A desktop represents a HTML page for a browser. In other words, this number controls the number of concurrent browser windows allowed per session.
| |
| − | | |
| − | A negative number means no limitation at all.
| |
| − | | |
| − | '''Note''': If you use <javadoc>org.zkoss.zk.ui.impl.GlobalDesktopCacheProvider</javadoc>, then you have to make this number much larger since it means the maximal allowed number of desktops ''per system''.
| |
| − | | |
| − | == The max-pushes-per-session Element ==
| |
| − | [Default: -1]
| |
| − | [Since 3.6.1]
| |
| − | | |
| − | It specifies the maximal allowed number of concurrent server-push connections per session.
| |
| − | | |
| − | A negative number (default) means no limitation at all. Zero means no server push is allowed at all.
| |
| − | | |
| − | Notices
| |
| − | * A desktop has at most one server-push connection.
| |
| − | * A desktop might be killed accidentally. For example, an user closes a browser window. In this case, the server might not be able to detect it. When specifying this, it is better to specify the maximal allowed number of desktops, too.
| |
| − | | |
| − | == The max-requests-per-session Element ==
| |
| − | [Default: 5]
| |
| − | | |
| − | It specifies the maximal allowed number of concurrent requests per session. Each time an user types an URL at the browser, it creates a request and the request ends after the response is sent to the browser. In other words, this number controls how many concurrent requests the same user can send.
| |
| − | | |
| − | A negative number means no limitation at all, but it is not recommended due to the possibility of the denial-of-service (DoS) attacks.
| |
| − | | |
| − | == The session-timeout Element ==
| |
| − | [Default: 0 ''(depending on the Web server)'']
| |
| − | | |
| − | It specifies the time, in seconds, between client requests before a session is invalidated. A negative time indicates the session should never timeout. The default zero means to use the system default (which is usually specified in <tt>web.xml</tt>).
| |
| − | | |
| − | == The timeout-message Element ==
| |
| − | [Optional]
| |
| − | [Since 5.0.5]
| |
| − | [Default: <i>a message defined in [http://docs.zkoss.org/wiki/Msgzk.properties MZk.UPDATE_OBSOLETE_PAGE]</i>]
| |
| − | | |
| − | It specifies the message to show when the session is timeout. Notice that it is used only if the timeout-uri element is <i>not</i> specified.
| |
| − | | |
| − | <source lang="xml">
| |
| − | <session-config>
| |
| − | <device-type>ajax</device-type>
| |
| − | <timeout-message>Session timeout. Please reload.</timeout-timeout>
| |
| − | </session-config>
| |
| − | </source>
| |
| − | | |
| − | === Internationalization ===
| |
| − | | |
| − | If you want to specify a Locale-dependent message, you could specify the key and prefix it with <code>label:</code> as follows.
| |
| − | | |
| − | <source lang="xml">
| |
| − | <session-config>
| |
| − | <device-type>ajax</device-type>
| |
| − | <timeout-message>label:timeout</timeout-timeout>
| |
| − | </session-config>
| |
| − | </source>
| |
| − | | |
| − | Then, you have to prepare the i3-label properties files as described in [[ZK_Developer%27s_Reference/Internationalization/Labels|ZK Developer's Reference]].
| |
| − | | |
| − | <source lang="text">
| |
| − | #i3-label.properties
| |
| − | timeout={
| |
| − | Session timeout.
| |
| − | (multi-line is allowed)
| |
| − | } | |
| − | </source>
| |
| − | | |
| − | === JavaScript ===
| |
| − | | |
| − | Instead of sending the message, you could provide the JavaScript code for the client to evaluate. To specify the JavaScript code, you have to prefix it with <code>script:</code>.
| |
| − | | |
| − | For example, you have a function called <tt>foo.timeout</tt> to handle the timeout effect, then you could configure <tt>WEB-INF/zk.xml</tt> as follows.
| |
| − | | |
| − | <source lang="xml">
| |
| − | <session-config>
| |
| − | <device-type>ajax</device-type>
| |
| − | <timeout-message>script:foo.timeout('Session Timeout')</timeout-timeout>
| |
| − | </session-config>
| |
| − | </source>
| |
| − | | |
| − | The code depends on the client. For Ajax devices, it has to be JavaScript.
| |
| − | | |
| − | == The timeout-uri Element ==
| |
| − | [Optional]
| |
| − | [Since 3.6.3]
| |
| − | [Default: <i>null</i>]
| |
| − | | |
| − | It specifies the target URI that will be used to redirect users to, when the desktop no longer exists – it is usually caused by session timeout.
| |
| − | | |
| − | If this element is omitted (default), an error message will be shown up at the browser to alert users for what happens. If you want to customize the message, please use the timeout-message element.
| |
| − | | |
| − | To reload the same URI again, you can specify an ''empty'' content as follows.
| |
| − | | |
| − | <source lang="xml">
| |
| − | <session-config>
| |
| − | <device-type>ajax</device-type>
| |
| − | <timeout-uri></timeout-uri>
| |
| − | </session-config>
| |
| − | </source>
| |
| − | | |
| − | Notice that this setting is applied only to the specified device ([[#The device-type Element|<device-type>]]), so remember to specify the correct device.
| |
| − | | |
| − | == The timer-keep-alive Element ==
| |
| − | [Default: false]
| |
| − | | |
| − | It specifies whether to keep the session alive, when receiving the <tt>onTimer</tt> event.
| |
| − | | |
| − | A session is considered as timeout (and then invalidated), if it doesn't receive any client request in the specified timeout interval (see the '''session-timeout''' element above).
| |
| − | | |
| − | By setting this option to true, the <tt>onTimer</tt> event, just like any other events, will reset the session timeout counter (and then keep the session alive until timeout). Notice that, if this option is false and the timer is shorter than the session timeout, the session won't be expired.
| |
| − | | |
| − | By default, this option is false. It means the <tt>onTimer</tt> event is ignored when handling the session timeout. In other words, the session will expire if no other event is received before timeout.
| |
| − | | |
| − | ==Version History==
| |
| − | | |
| − | {| border='1px' | width="100%"
| |
| − | ! Version !! Date !! Content
| |
| − | |-
| |
| − | | 5.0.5
| |
| − | | October 2010
| |
| − | | The support of Custom Message and JavaScript was introduced.
| |
| − | |}
| |
| − | | |
| | {{ZKConfigurationReferencePageFooter}} | | {{ZKConfigurationReferencePageFooter}} |