public interface DateFormatAndStorage
DataSources and databound components may define fields of type date,
time, or datetime.
Fields of type date are considered to be logical
Dates with no time
value, such as a holiday or birthday. In the browser, values for "date" fields are stored
as Date objects, but when formatted for display to the user, they are typically displayed
without any time information.
When using the Smart GWT server framework, "date" values are automatically transmitted with year, month and day preserved and time value ignored.
When sent or received in XML or JSON, date field values should be serialized in the
XML Schema date format
-
YYYY-MM-DD - are expected to be received in the same format. Any time value
present for a "date" field is ignored.
The DateUtil.createLogicalDate() method may be used to create a new Date object to represent a logical date value on the browser.
System wide formatting for dates may be controlled via the
DateUtil.setNormalDisplayFormat() and DateUtil.setShortDisplayFormat()
methods.
Fields of type datetime are dates with full time
information.
In the browser, values for datetime fields are stored as Date objects.
When using the Smart GWT server framework, "datetime" values are automatically transmitted such that the resulting Date object has the same GMT/UTC timestamp. This value is referred to elsewhere in these discussions as an "epoch value", and it is precisely defined as: the number of milliseconds since midnight on January 1st 1970 in the UTC timezone (because 1970-01-01 00:00:00 UTC is "the epoch").
When sent or received in XML or JSON, datetime field values should be serialized out as full
datetimes using the standard
XML Schema datetime
format
(EG:2006-01-10T12:22:04-04:00). If no timezone offset is supplied, the value
is assumed to be GMT/UTC.
System wide formatting for datetimes may be controlled via the
DateUtil.setShortDatetimeDisplayFormat() method. Datetimes will be displayed to the
user in browser local time by default (see also timezone notes below).
Fields of type time are time values in the absence
of a day, such as
the beginning of the workday (9:00). In the browser, values for "time" fields are stored as
Date objects with the time in browser local time. The date information has no meaning and
only the time information is displayed to the user.
Time formatting is handled by the String class APIs.
When using the Smart GWT server framework, "time" values are automatically transmitted
such that the resulting Date object has the same hour, minute and second values in local
time, and year/month/day is ignored.
When sent or received in XML or JSON, date field values should be serialized as hours,
minutes and seconds using the standard
XML Schema time format
-
"22:01:45". Timezone is not relevant and should be omitted.
The DateUtil.createLogicalTime() method may be used to create a new Date object to represent a logical time value on the browser.
By default, "datetime" values will be shown to the user in browser local time, as derived from the native browser locale. Developers may modify this behavior by specifying an explicit display timezone via String.
Note that depending on the specific date being displayed, a Daylight Savings Time offset may also be applied based on the browser locale. To disable this behavior set String to false.
If a custom timezone is specified, it will be respected by all TimeDisplayFormats, and
by the standard short DateDisplayFormats when formatting
dates representing datetime
type values. However native JavaScript Date formatters,
including toLocaleString() will not respect the specified timezone. Developers
specifying a custom timezone may therefore wish to modify the
DateUtil.setNormalDisplayFormat() to avoid using a native JS Date formatter function.
Note that in addition to the system-wide date, datetime and time-formatting settings described
above, databound components also support applying custom display formats for date values.
Typically this can be achieved via a custom dateFormatter or
timeFormatter at the field level (see DataSourceField.dateFormatter,
DataSourceField.timeFormatter
and for example ListGridField.dateFormatter).
Date formatting may also be configured at the component level by setting the
dateFormatter, datetimeFormatter and timeFormatter
attributes (See for example ListGrid.dateFormatter, ListGrid.timeFormatter,
and ListGrid.datetimeFormatter).
Support for timezones and datetime values varies across the database vendors. There is a standard approach proposed by the SQL:1999 standard, but as is often the case with SQL standards, support is far from universal and there are many idiosyncrasies. This leads to a situation where different databases offer different ways for an internationalized application to store datetimes, and some offer facilities that others lack. For example, PostgreSQL supports the SQL:1999 standard TIMESTAMP WITH TIME ZONE syntax; MySQL allows you to achieve the same end by providing proprietary methods to set a timezone globally or per-connection; Informix has no explicit timezone support at all. For these reasons, Smart GWT Server implements framework-level support for difficult datetime issues like timezones and Daylight Saving Time, and does not rely on any native database features.
As previously discussed, datetime values are transmitted between client and server by encoding and decoding in UTC, ensuring that there is no shift in the datetime value. If the browser and server are in different timezones, Date.toString() on the server will show a different date and time than you see in the browser, but the underlying datetime value is the same.
Then, for storing to a database, Smart GWT's storage behavior is governed by the
server.properties flag sql.{database-name}.useUTCDateTimes. For
example:
sql.defaultDatabase: AppDatabase
sql.AppDatabase.database.type: mysql
sql.AppDatabase.driver: com.mysql.jdbc.jdbc2.optional.MysqlDataSource
sql.AppDatabase.useUTCDataTimes: true
etc
If the useUTCDateTimes flag is set, Smart GWT generates SQL that renders
datetimes as UTC values; otherwise it generates SQL that renders datetime values in the
JVM's local timezone. This process is reversed when datetime values are fetched back out
of the database, so values round-trip correctly.
To aid understanding, consider this round-trip example. We have a user in New York and a user in London; the server is in San Francisco and is configured to use the US Pacific timezone (this is mentioned explicitly because servers are often configured to use UTC, wherever they are in the world). Our New York user saves a record representing an online meeting to take place on May 23 2016 at 2pm local time. This is what happens:
useUTCDateTimes flag is set, the server renders this epoch value as
a UTC time when generating the SQL. It is important to understand that this concept of the
datetime being UTC is something we are doing at the framework level; the database may think
it is storing a local datetime, or a UTC datetime, or it may not consider the issue of
timezones at all. The important thing is, we told it to insert '2016-05-23 18:00:00', so
we can reasonably expect that this is the value we will get out of it when we read the row
backuseUTCDateTimes flag is not set, the server renders this epoch value
as a time in the JVM's local timezone when generating the SQL. Again, keep in mind that the
concept of the datetime being in a particular timezone is something we are doing at the
framework level; as above, the important thing is, we told it to insert '2016-05-23 11:00:00'
(because it is May so San Francisco is on Pacific Daylight Time, which is GMT-0700), so that
is what we will get back when we read it (there are cases where this may not be true; see
the section "Store using UTC or local timezone?" below)useUTCDateTimes flag
(in fact, it isn't always that straightforward behind the scenes because some databases/JDBC
drivers perform automatic conversions on datetime values that cannot be suppressed, but
Smart GWT Server compensates for such cases)
As described above, Smart GWT Server can be configured to store datetimes using either UTC or the JVM's local timezone. On the face of it, there is little to choose between the two: Smart GWT will ensure that values are consistent across server and client regardless of which you choose. However, we recommend that you choose UTC as your storage strategy, for two compelling reasons
Date and time storage and timezones can be confusing, and Isomorphic receives a steady stream of false bug reports from users that are incorrectly analyzing logs and diagnostics. Please consider the following points when troubleshooting issues such as date values changing to a different day, or datetime value shifting when saved and reloaded:
Whenever you use Date.toString() (client or server-side) the value you get is based on the server or browser timezone.
Perhaps you are troubleshooting an issue with datetimes and you try to log the value of a Date like this:
Date someDate = <some expression>;
log("date value is: " + someDate);
Code like this will show the datetime value in the server's timezone if executed
server-side, and in the client's timezone if executed client-side. If they are in different
timezones, the hour or day will be different, whereas the actual datetime value -
milliseconds since epoch as retrieved by Date.getTime() - is the same. To correctly
compare two datetime values, compare the result of getTime().
This is the inverse situation as for "datetime" values. As explained above, "date" values have no meaningful values for time fields (hours/minutes/seconds) and "time" values have no meaningful values for date fields (month/day/year). Here, the result of Date.getTime() is not meaningful, and values should be compared via getHours(), getMonth() et al.
If you've called setDefaultDisplayTimezone() to cause all datetime values to be rendered in a particular timezone, this does not affect the return values of Date.getHours(), which will still return values for the browser's current timezone. Hence it is not a bug if you have a "datetime" value which is displaying as 4am, but getHours() returns 10 or some other number. This just reflects the timezone offset between the timezone passed to setDefaultDisplayTimezone() and the browser's local timezone.
If you declare a field as type "date" but values you provide actually contain specific hours, minutes and seconds, these will not be preserved. The system will discard or reset the hours, minutes and seconds in the course of serialization or editing. Likewise if you declare a field as type "time" but actually provide values where year, month and day have meaning, these values will be dropped.
Similarly, DateItem expects values for "date" fields, TimeItem expects values for "time" fields, and DateTimeItem expects values for "datetime" fields. Providing the wrong type of value to a control, such as providing a value from a "datetime" field to a DateItem, will have unspecified results.
If you want to take the date and time aspects of a "datetime" value and edit them in separate
FormItems, use
getLogicalDateOnly() and DateUtil.getLogicalTimeOnly() to
split a datetime value into date and time values, and use
DateUtil.combineLogicalDateAndTime() to re-combine
such values. Otherwise it is very
easy to make mistakes related to timezone offsets.
If you're having a problem with round-tripping "datetime" values or "date" values shifting to another day, you need to isolate the problem to a specific layer. Bearing in mind the techniques above for comparing values, you potentially need to look at any/all of the following:
DataSource.fetchData() and inspect the
data in the callback)
DataSource.transformRequest() is a good place to check)