hirondelle.web4j.request
Interface TimeZoneSource

All Known Implementing Classes:

TimeZoneSourceImpl

public interface TimeZoneSource

Return the TimeZone associated with a given request.

See BuildImpl for important information on how this item is configured. BuildImpl.forTimeZoneSource() returns the configured implementation of this interface. See TimeZoneSourceImpl for a default implementation. This interface is similar to LocaleSource, and is used in much the same way.

In general, a TimeZone is used for two distinct operations :

• render Date objects
• parse user input into a Date object

By default, a JRE will perform such operations using the implicit value returned by TimeZone.getDefault(). The main reason for defining this interface is to provide an alternative to this mechanism, since it is inappropriate for most server applications.

For your Actions, the fastest way to access the time zone is usually via ActionImpl.getTimeZone().

The TimeZone returned by this interface is used by WEB4J for :

• user response messages containing dates
• presenting ResultSets as reports with Report
• displaying dates with ShowDate
• populating forms
• parsing form entries

A very large number of policies can be defined by implementations of this interface. Possible sources of TimeZone information include :

• a single setting in web.xml, place into application scope upon startup
• an object stored in session scope
• a request parameter
• a request header
• a cookie

Java versus Databases

Java always represents dates internally using the number of milliseconds from its epoch. In Java, a Date is always an unambiguous instant. When parsing and formatting dates, it will always use a TimeZone (either implicity or explicitly). On the other hand, it is often that the case that a database column storing a date does not store dates internally in an unambiguous way. For example, many dates are stored as just '05-31-2007 06:00', for example, without any time zone information.

If that is the case, then there is a mismatch : constructing a Date out of many database columns will require a TimeZone to be specified, either explicitly or implicitly. See ResultSet.getDate(int, java.util.Calendar), PreparedStatement.setDate(int, java.sql.Date, java.util.Calendar), and related methods.

The storage of dates in a database is not handled by this interface. That is treated as a separate issue.

web.xml

There are two settings related to time zones in web.xml. The two settings correspond to two distinct ideas : the time zone appropriate for dates presented to the end user, and the time zone in which the date is stored.

The DefaultUserTimeZone setting is used by TimeZoneSourceImpl. For applications that use only a single time zone, then this setting is used to specify that time zone. It provides independence of the default JRE time zone, which will vary according to the server location. For applications that use more than one time zone, then this same setting can be reinterpreted as the default time zone, which can be overridden by implementations of this interface.

The TimeZoneHint setting is used by the WEB4J data layer to indicate the time zone in which a date should be stored. If specified, this setting is communicated to the underlying database driver using PreparedStatement.setTimestamp(int, java.sql.Timestamp, java.util.Calendar) and ResultSet.getTimestamp(int, java.util.Calendar).

Method Summary

TimeZone

get(HttpServletRequest aRequest) Return a TimeZone corresponding to a given underlying request.

Method Detail

get

TimeZone get(HttpServletRequest aRequest)

Return a TimeZone corresponding to a given underlying request.