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    }