Examples of hirondelle.web4j.request.TimeZoneSource

Return the {@link TimeZone} associated with a given request.

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

In general, a {@link TimeZone} is used for two distinct operations :

render {@link java.util.Date} objects
parse user input into a Date object

By default, a JRE will perform such operations using the implicit value returned by {@link 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 {@link ActionImpl#getTimeZone()}.

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

user response messages containing dates
presenting ResultSets as reports with {@link hirondelle.web4j.database.Report}
displaying dates with {@link hirondelle.web4j.ui.tag.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 {@link java.util.Date} is always an unambiguous instant. When parsing and formatting dates, it will always use a {@link 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 {@link java.util.Date} out of many database columns will require a {@link TimeZone} to be specified, either explicitly or implicitly.See {@link java.sql.ResultSet#getDate(int,java.util.Calendar)}, {@link java.sql.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 {@link 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 {@link java.sql.PreparedStatement#setTimestamp(int,java.sql.Timestamp,java.util.Calendar)}and {@link java.sql.ResultSet#getTimestamp(int,java.util.Calendar)}.