Time Zone"

From Documentation
m
m
Line 3: Line 3:
 
__TOC__
 
__TOC__
  
The time zone used to process requests and events is, by default, determined by the JVM's preferences (by use of the <tt>getDefault</tt> method of <tt>java.util.TimeZone</tt>).
+
=Overview=
 +
The time zone used to process requests and events is, by default, determined by the JVM's default (by use of the <tt>getDefault</tt> method of <tt>java.util.TimeZone</tt>)<ref>Unlike locale, there is no way to determine the time zone for each browser</ref>.
  
'''Note''': Unlike locale, there is no standard way to determine the time zone for each browser.
+
In this section, we'd like to discuss how to configure ZK to use a time zone other than JVM's default. For example, you might want to use the preferred time zone that a user specified in his or her profile.
  
Like Locale, the time zone for a given application and session is configurable. For example, you might want to use the preferred time zone that a user specified in his or her profile, if you maintain user profiles in the server.
+
<blockquote>
 +
----
 +
<references/>
 +
</blockquote>
  
 +
=The decision sequence of time zone=
  
=== The Application Attribute: <tt>px_preferred_time_zone</tt> ===
+
The time zone is decided in the following sequence.
[Since 3.6.3]
 
  
If you want to use the same time zone for all users, you can specify the time zone in the application attribute (<tt>WebApp</tt>, aka., <tt>ServletContext</tt>) called <tt>px_preferred_time_zone</tt>.
+
# It checks if an attribute called <code>org.zkoss.web.preferred.timeZone</code> defined in the HTTP session (or <javadoc type="interface">org.zkoss.zk.ui.Session</javadoc>). If so, use it.
 +
# It checks if an attribute called <code>org.zkoss.web.preferred.timeZone</code> defined in the Servlet context (or <javadoc type="interface">org.zkoss.zk.ui.Application</javadoc>). If so, use it.
 +
# It checks if a property called <code>org.zkoss.web.preferred.timeZone</code> defined in the library property (i.e., <javadoc>org.zkoss.lang.Library</javadoc>). If so, use it.
 +
# If none of them is found, JVM's default will be used.
  
'''Tip''': To avoid typo, you can use the constant: <javadoc method="PREFERRED_TIME_ZONE">org.zkoss.web.Attributes</javadoc>.
+
With this sequence in mind, you could configure ZK to use the correct time zone based on the application requirements.
  
=== The Session Attribute: <tt>px_preferred_time_zone</tt> ===
+
==Application-level time zone==
ZK will check if a session attribute called <tt>px_preferred_time_zone</tt> is defined. If defined, it uses as the default time zone for the session instead of the system default. Thus, you can control the time zone of a session by storing the preferred time zone in this attribute, after, say, a user logins as depicted in the previous section.
 
  
'''Tip''': To avoid typo, you can use the constant: <javadoc method="PREFERRED_TIME_ZONE">org.zkoss.web.Attributes</javadoc>
+
If you want to use the same time zone for all users of the same application, you can specify the time zone in the library property. For example, you could specify the following in <tt>WEB-INF/zk.xml</tt>:
  
=== The Request Interceptor ===
+
<source lang="xml">
Like Locale, you can prepare the time zone for the given session by use of the request interceptor.
+
<library-property>
 +
    <name>org.zkoss.web.preferred.timeZone</name>
 +
    <value>GMT-8</value>
 +
</library-property>
 +
</source>
  
 +
where the value can be anything accepted by the <code>getTimeZone</code> method of <code>java.util.TimeZone</code>
 +
 +
Alternatively, if you prefer to specify it in Java, you could invoke <javadoc method="setProperty(java.lang.String, java.lang.String)">org.zkoss.lang.Library</javadoc>. Furthermore, to avoid typo, you could use <javadoc method="PREFERRED_TIME_ZONE">org.zkoss.web.Attributes</javadoc> as follows.
 +
 +
<source lang="java">
 +
Library.setProperty(Attributes.PREFERRED_TIME_ZONE, "PST");
 +
</source>
 +
 +
== Per-user time zone ==
 +
 +
Because ZK will check if a session attribute for the default time zone, you could configure ZK to have per-user time zone by specifying the attribute in a session.
 +
 +
For example, you can do this when a user logins.
 +
 +
<source lang="java" >
 +
void login(String username, String password) {
 +
    //check password
 +
    ...
 +
    TimeZone preferredTimeZone = ...; //decide the time zone (from, say, database)
 +
    session.setAttribute(Attributes.PREFERRED_TIME_ZONE, preferredTimeZone);
 +
    ...
 +
}
 +
</source>
 +
 +
= The Request Interceptor =
 +
 +
Like configuring locale, you can prepare the time zone for the given session by use of the request interceptor. Please refer to [[http://books.zkoss.org/wiki/ZK_Developer%27s_Reference/Internationalization/Locale#The_Request_Interceptor Locale]] for more information.
  
 
=Version History=
 
=Version History=

Revision as of 11:05, 1 October 2010

Overview

The time zone used to process requests and events is, by default, determined by the JVM's default (by use of the getDefault method of java.util.TimeZone)[1].

In this section, we'd like to discuss how to configure ZK to use a time zone other than JVM's default. For example, you might want to use the preferred time zone that a user specified in his or her profile.


  1. Unlike locale, there is no way to determine the time zone for each browser

The decision sequence of time zone

The time zone is decided in the following sequence.

  1. It checks if an attribute called org.zkoss.web.preferred.timeZone defined in the HTTP session (or Session). If so, use it.
  2. It checks if an attribute called org.zkoss.web.preferred.timeZone defined in the Servlet context (or Application). If so, use it.
  3. It checks if a property called org.zkoss.web.preferred.timeZone defined in the library property (i.e., Library). If so, use it.
  4. If none of them is found, JVM's default will be used.

With this sequence in mind, you could configure ZK to use the correct time zone based on the application requirements.

Application-level time zone

If you want to use the same time zone for all users of the same application, you can specify the time zone in the library property. For example, you could specify the following in WEB-INF/zk.xml:

<library-property>
    <name>org.zkoss.web.preferred.timeZone</name>
    <value>GMT-8</value>
</library-property>

where the value can be anything accepted by the getTimeZone method of java.util.TimeZone

Alternatively, if you prefer to specify it in Java, you could invoke Library.setProperty(String, String). Furthermore, to avoid typo, you could use Attributes.PREFERRED_TIME_ZONE as follows.

Library.setProperty(Attributes.PREFERRED_TIME_ZONE, "PST");

Per-user time zone

Because ZK will check if a session attribute for the default time zone, you could configure ZK to have per-user time zone by specifying the attribute in a session.

For example, you can do this when a user logins.

 void login(String username, String password) {
     //check password
     ...
     TimeZone preferredTimeZone = ...; //decide the time zone (from, say, database)
     session.setAttribute(Attributes.PREFERRED_TIME_ZONE, preferredTimeZone);
     ...
 }

The Request Interceptor

Like configuring locale, you can prepare the time zone for the given session by use of the request interceptor. Please refer to [Locale] for more information.

Version History

Version Date Content
     



Last Update : 2010/10/01

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