Calendar:Feature Implementations:Timezones

<<Back to Features

Timezone Backend Design (DRAFT)

Discussion in mozilla.dev.apps.calendar

In general, when we read in calendars, we'll get VTIMEZONEs that fall into two categories: ones that are builtin to our implementation, and foreign timezones. Authoritatively, we'll store these in single files, each containing a single VTIMEZONE, but they'll be cached in and used from SQLite databases (we may choose not to ship the directory tree version of the builtin timezones, since that just adds unnecessary download size).

When we read in calendars (or are given new VCOMPONENTS like VEVENTS or VTODOS),there will be a number of different types of TZIDs that we'll find. Below, I will use "Foreign" timezone to refer to a zone that was not created by the current or previous version of the currently running Sunbird/Lightning. For example, if a user on 0.3.1 receives an event from 0.5, that would be handled as a "Foreign" timezone. However, if that user receives an event with a 0.3 timezone definition, that would NOT be a "Foreign timezone". Each of these timezone types will be dealt with according to the list below:

Current Mozilla Timezones

• Starts with /mozilla.org/current_dtstamp/
  • The current internal database version
  • Nothing to do here
  • Raw path: installdir/timezones/current_dtstamp/Continent/City.ics
  • DB path: installdir/timezones/current_dtstamp/builtin-zones.sqlite3

Older Mozilla Timezones

• Starts with /mozilla.org/older_dtstamp/
  • An older internal version
  • Change reference to current version
  • Raw path, DB path: (none, see current version)

Newer Mozilla Timezones

• Starts with /mozilla.org/newer_dtstamp/
  • treat as any other globally unique zone (see below)

Foreign Zones -- Timezones from other applications (including newer Mozilla zones)

• Other
  • DB path: profiledir/timezones/imported-zones.sqlite3
  • Assign a UUID for tracking
    • Claims to be globally unique
    • Not in "foreign timezone database"? Add it.
    • Already in database? Compare...
      • ==, nothing to do
      • !=, reject (in the future, we could rename)
    • Raw path: profiledir/timezones/uuid/

Other Issues

Foreign Zone Lifetime

Until there is a reliable "standard" copy of timezone definitions available from a server side timezone database, we will need to maintain non-Sunbird/Lightning timezones. Once there is a standard copy of timezone definitions that we can depend on to be current, we can consider merging "foreign" timezones into the standard copy, and we may not need to keep copies of those zones. In the meantime, I propose that we use a refcounting scheme in order to manage the lifetime of the foreign timezone definitions.

• Use refcounts to manage the lifetime of a all zones (including the built-in ones, this is useful for updating our definitions).
  • Once the number of events referencing that zone goes to zero, we remove that zone from the database
  • Should these refcounts be maintained in the flat file copy of the timezone? I'm not sure, it depends on the function of the flat files (see TODO's below)
  • Each event that references this foreign zone will add one to the zone's refcount. When the event is deleted (an entire event -- not an instance of an appointment is deleted) then the refcount will be decremented by 1.

Displaying Foreign Timezones

• Users will NOT be able to create events using foreign zones.
• Users will be able to edit a VEVENT or VTODO that contains a Foreign timezone reference without disturbing the timezone reference (unless the user edits the timezone specification, of course).
• Users will be able to view a foreign timezone in our timezone picker.
  • We will do this by displaying the TZID in text
  • If we have a graphical picker, we will highlight the proper zone offset, so that the user can see geographically where the zone lies.
  • (Enhancement) If needed, we may be able to map the zone using the TZID to our set of known zones so that a proper city location can be displayed to the user. In most cases we can do this because by convention TZID's will usually contain enough descriptive text for us to establish a linkage with our own city list from our internal zones. Of course, should this not be possible for the given TZID, then we will have to forgo this level of mapping and will have to rely instead on showing the user the TZID and the UTC offset.

Updating timezone Definitions

• Updating Built-in Timezones
• All timezones in database will have a new TZID field. This will be blank until an update occurs. When the update occurs, the field will be populated with a key referencing the new TZID, and the subsystem will use this new key to map the old timezone definition to the updated timezone defnition.
• When updating, foreign timezones will be left alone. They will not be updated or destroyed. (When there is a standard timezone database service, we will revisit this.)
• When a VEVENT or VTODO performs a lookup on an old timezone definition, the newer definition will be returned, and the refcounts will be handled as follows:
  • • Old timezone defintion refcount-- (if this is 0 we will remove the old definition)
    • New timezone definition refcount++

Timezone Mappings between Builtin zones and Foreign Zones

• While there is no standard for timezone mappings, there are conventions
• Other implementations that use the Olson database should be fairly trivial to map, we simply compare the offsets then the continent, then the city.
• The other primary convention we will find will be the Windows timezone naming system, which can be mapped to Olson.
• In order to map between the flat file store and the database store for the foreign timezones, it would be fairly simple to have a path descriptor and/or filename (since we know it will live in the Profile Dir) in the database. Then the timezone service can simply query the database to find the file information and use that. TODO: Should the database be able to operate using only a flat-file system?

TODO

• What problems does the flat file system solve? What does it gain over the database, or is it simply a handy backup?
• Do we need a user accessible backup utility, perhaps something that will dump all the timezone definitions (builtin and foreign) to a set of flat files?
• How much user control do users exercise over the timezone database? Is there/should there be an "Update Timezone Definitions" button in prefs somewhere?
• Is there a cost to using a different database for foreign zones vs. builtin zones? Would it make comparisons simpler/more performant to use the same sqlite database for both sets of timezones? I tend to think we should use the same database for both, is there some valid reason to not do this?

References:

• bug 314339 – need to handle non-native timezone bits
• bug 363191 - Handle Timezones more efficiently (Timezone Database)