Resources | Resources |



ITimeZone interface

The ITimeZone interface provides methods for obtaining information about a given timezone.

A timezone is an area which, at any given time, is at a particular offset from Coordinated Universal Time (UTC) based on a predefined set of rules. The area can be a whole country or continent or a part thereof. For example, America/Los_Angeles is a timezone that describes an area where Los Angeles is one of the major cities and is eight hours behind UTC. When daylight savings rules are in effect, it is seven hours behind. The rules that determine when and how much the offset can change are based on decisions made by local authorities.

The methods in the ITimeZone interface provide information such as:

  • Descriptive names for timezones
  • Latitude and longitude of the main city in a given timezone
  • Number of subtypes
  • Offsets from UTC for each subtype
  • Daylight savings support
  • Timezone transition times
  • Notifications when such transition rules change due to changes in international timezone rules

The ITimeZone interface allows applications to query the descriptive names of the timezones in various languages, provided the system has been configured to support such descriptive names in multiple languages.

The timezone data is stored in an SQL database. This provides the following advantages:

  • Future updatability by replacing the entire database or updating parts of it.
  • Proven, reliable and robust data store.

…with the following costs:

  • SQL database that stores timezone data could be larger than a compact, proprietary format.
  • Requires dbc, which is included as part of Brew MP.

Timezone database schema

The timezone information is stored in database files containing at least three tables for timezone names and coordinates (one table per supported language), offsets, and transitions.

The schema for the timezone database looks like this:

(Name TEXT,
 Alternate_Name TEXT,
 Alternate_Display_Name TEXT,
 Alternate_DLT_Name TEXT,
 Alternate_STD_Name TEXT,
 Latitude REAL,Longitude REAL);
CREATE TABLE Transitions (TZ_rowID INTEGER,transitionStartTime 
INTEGER,transitionEndTime INTEGER,subtypeIndex INTEGER);
CREATE TABLE SubTypes (TZ_rowID INTEGER,subTypeIndex 

The timezone names can be in multiple languages with one table per language to avoid multiple databases that would increase EFS usage. The names are stored in a table named after the language code. The language is a sequence of four characters consisting of the ISO 639-1 language code (2 characters) followed by the ISO 3166 A2 country code (2 characters). The country code is optional. In the case this optional code is not present, two underscores (instead of spaces as in the timezone APIs) are inserted in its place. For example: Korean (LNG_KOREAN) is defined as "ko__" without the optional country code ("ko" for language code and two underscores for country code). Portuguese used in Brazil (LNG_PORTUGUESE_BRAZIL) is defined as "ptbr" (0x72627470) with the country code ("pt" for language code and "br" for country code). There will be one such table for every language supported.