001 package hirondelle.web4j.request; 002 003 import hirondelle.web4j.action.ActionImpl; 004 import java.util.TimeZone; 005 import javax.servlet.http.HttpServletRequest; 006 007 /** 008 Return the {@link TimeZone} associated with a given request. 009 010 <P>See {@link hirondelle.web4j.BuildImpl} for important information on how this item is configured. 011 {@link hirondelle.web4j.BuildImpl#forTimeZoneSource()} 012 returns the configured implementation of this interface. See {@link TimeZoneSourceImpl} for a default implementation. 013 This interface is similar to {@link LocaleSource}, and is used in much the same way. 014 015 <P>In general, a {@link TimeZone} is used for two distinct operations : 016 <ul> 017 <li>render {@link java.util.Date} objects 018 <li>parse user input into a <tt>Date</tt> object 019 </ul> 020 021 <P>By default, a JRE will perform such operations using the <em>implicit</em> value returned by 022 {@link TimeZone#getDefault()}. The main reason for defining this interface is to 023 provide an alternative to this mechanism, since it is inappropriate for most server applications. 024 025 <P><i>For your Actions, the fastest way to access the time zone is usually via {@link ActionImpl#getTimeZone()}.</i> 026 027 <P>The <tt>TimeZone</tt> returned by this interface is used by WEB4J for : 028 <ul> 029 <li>user response messages containing dates 030 <li>presenting <tt>ResultSets</tt> as reports with {@link hirondelle.web4j.database.Report} 031 <li>displaying dates with {@link hirondelle.web4j.ui.tag.ShowDate} 032 <li>populating forms 033 <li>parsing form entries 034 </ul> 035 036 <P>A very large number of policies can be defined by implementations of this interface. 037 Possible sources of <tt>TimeZone</tt> information include : 038 <ul> 039 <li>a single setting in <tt>web.xml</tt>, place into application scope upon startup 040 <li>an object stored in session scope 041 <li>a request parameter 042 <li>a request header 043 <li>a cookie 044 </ul> 045 046 <h3>Java versus Databases</h3> 047 <P>Java always represents dates internally using the number of milliseconds from its epoch. In Java, a 048 {@link java.util.Date} is always an unambiguous instant. When parsing and formatting dates, it will always use 049 a {@link TimeZone} (either implicity or explicitly). On the other hand, it is often that the case that 050 a database column storing a date does <em>not</em> store dates internally in an unambiguous way. For example, 051 many dates are stored as just '<tt>05-31-2007 06:00</tt>', for example, without any time zone information. 052 053 <P>If that is the case, then there is a mismatch : constructing a {@link java.util.Date} out of many 054 database columns will <em>require</em> a {@link TimeZone} to be specified, either explicitly or implicitly. 055 See {@link java.sql.ResultSet#getDate(int, java.util.Calendar)}, 056 {@link java.sql.PreparedStatement#setDate(int, java.sql.Date, java.util.Calendar)}, and related methods. 057 058 <P>The storage of dates in a database is <em>not</em> handled by this interface. That is 059 treated as a separate issue. 060 061 <h3>web.xml</h3> 062 There are two settings related to time zones in <tt>web.xml</tt>. The two settings correspond to two 063 distinct ideas : the time zone appropriate for dates <em>presented</em> to the end user, and the time zone in 064 which the date is <em>stored</em>. 065 066 <P>The <tt>DefaultUserTimeZone</tt> setting is used by {@link TimeZoneSourceImpl}. 067 For applications that use only a single time zone, then this setting is used to specify that time 068 zone. It provides independence of the default JRE time zone, which will vary according to the server location. 069 For applications that use more than one time zone, then this same setting can be reinterpreted as the 070 <em>default</em> time zone, which can be overridden by implementations of this interface. 071 072 <P>The <tt>TimeZoneHint</tt> setting is used by the WEB4J data layer to indicate the time zone in 073 which a date should be stored. If specified, this setting is communicated to the underlying 074 database driver using {@link java.sql.PreparedStatement#setTimestamp(int, java.sql.Timestamp, java.util.Calendar)} 075 and {@link java.sql.ResultSet#getTimestamp(int, java.util.Calendar)}. 076 */ 077 public interface TimeZoneSource { 078 079 /** Return a {@link TimeZone} corresponding to a given underlying request. */ 080 public TimeZone get(HttpServletRequest aRequest); 081 082 }