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

The allowed child elements include session-timeout and max-desktops-per-session. You might have multiple session-config elements in one zk.xml.

 <session-config>
     <session-timeout>1800</session-timeout>
     <timer-keep-alive>false</timer-keep-alive>
     <max-desktops-per-session>15</max-desktops-per-session>
     <max-requests-per-session>5</max-requests-per-session>
     <max-pushes-per-session>3</max-pushes-per-session>
 </session-config>

The automatic-timeout Element

[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 if the user does nothing.

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 (<device-type>), so remember to specify the correct device. For example,

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

Page-level Automatic Timeout

If you want to specify whether to automatically timeout for particular pages, you can use 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,

<!-- my timeout page -->
<?page automaticTimeout="false"?>
...

The device-type Element

[Optional]
[Since 3.6.3]
[Default: ajax]

It specifies the device type that <timeout-uri> and <automatic-timeout> are applied to. By default, it is ajax. If you want to specify the timeout URI for mobile device, use mil.

Notice that only <timeout-uri> and <automatic-timeout> 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 GlobalDesktopCacheProvider, 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 web.xml).

The timeout-uri Element

[Optional]
[Since 3.6.3]
[Default: null]

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, an error message will be shown up at the browser to alert users for what happens.

To reload the same URI again, you can specify an empty content as follows.

<session-config>
	<device-type>ajax</device-type>
	<timeout-uri></timeout-uri>
</session-config>

Notice that this setting is applied only to the specified device (<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 onTimer 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 onTimer 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 onTimer event is ignored when handling the session timeout. In other words, the session will expire if no other event is received before timeout.