Save This Page
Home » openjdk-7 » sun » util » calendar » [javadoc | source]
sun.util.calendar
public class: ZoneInfoFile [javadoc | source]
java.lang.Object
   sun.util.calendar.ZoneInfoFile
ZoneInfoFile reads Zone information files in the <java.home>/lib/zi directory and provides time zone information in the form of a ZoneInfo object. Also, it reads the ZoneInfoMappings file to obtain time zone IDs information that is used by the ZoneInfo class. The directory layout and data file formats are as follows.

Directory layout

All zone data files and ZoneInfoMappings are put under the <java.home>/lib/zi directory. A path name for a given time zone ID is a concatenation of <java.home>/lib/zi/ and the time zone ID. (The file separator is replaced with the platform dependent value. e.g., '\' for Win32.) An example layout will look like as follows.

<java.home>/lib/zi/Africa/Addis_Ababa
/Africa/Dakar
/America/Los_Angeles
/Asia/Singapore
/EET
/Europe/Oslo
/GMT
/Pacific/Galapagos
...
/ZoneInfoMappings
A zone data file has specific information of each zone. ZoneInfoMappings has global information of zone IDs so that the information can be obtained without instantiating all time zones.

File format

Two binary-file formats based on a simple Tag-Length-Value format are used to describe TimeZone information. The generic format of a data file is:

DataFile {
u1 magic[7];
u1 version;
data_item data[];
}
where magic is a magic number identifying a file format, version is the format version number, and data is one or more data_items. The data_item structure is:
data_item {
u1 tag;
u2 length;
u1 value[length];
}
where tag indicates the data type of the item, length is a byte count of the following value that is the content of item data.

All data is stored in the big-endian order. There is no boundary alignment between date items.

1. ZoneInfo data file

Each ZoneInfo data file consists of the following members.

ZoneInfoDataFile {
u1 magic[7];
u1 version;
SET OF1 {
transition transitions2;
offset_table offsets2;
simpletimezone stzparams2;
raw_offset rawoffset;
dstsaving dst;
checksum crc32;
gmtoffsetwillchange gmtflag2;
}
}
1: an unordered collection of zero or one occurrences of each item
2: optional item
magic is a byte-string constant identifying the ZoneInfo data file. This field must be "javazi\0" defined as #JAVAZI_LABEL .

version is the version number of the file format. This will be used for compatibility check. This field must be 0x01 in this version.

transition, offset_table and simpletimezone have information of time transition from the past to the future. Therefore, these structures don't exist if the zone didn't change zone names and haven't applied DST in the past, and haven't planned to apply it. (e.g. Asia/Tokyo zone)

raw_offset, dstsaving and checksum exist in every zoneinfo file. They are used by TimeZone.class indirectly.

1.1 transition structure

transition {
u1 tag; // 0x04 : constant
u2 length; // byte length of whole values
s8 value[length/8]; // transitions in `long'
}
See ZoneInfo.transitions about the value.

1.2 offset_table structure

offset_table {
u1 tag; // 0x05 : constant
u2 length; // byte length of whole values
s4 value[length/4]; // offset values in `int'
}

1.3 simpletimezone structure

See ZoneInfo.simpleTimeZoneParams about the value.

simpletimezone {
u1 tag; // 0x06 : constant
u2 length; // byte length of whole values
s4 value[length/4]; // SimpleTimeZone parameters
}
See ZoneInfo.offsets about the value.

1.4 raw_offset structure

raw_offset {
u1 tag; // 0x01 : constant
u2 length; // must be 4.
s4 value; // raw GMT offset [millisecond]
}
See ZoneInfo.rawOffset about the value.

1.5 dstsaving structure

Value has dstSaving in seconds.

dstsaving {
u1 tag; // 0x02 : constant
u2 length; // must be 2.
s2 value; // DST save value [second]
}
See ZoneInfo.dstSavings about value.

1.6 checksum structure

checksum {
u1 tag; // 0x03 : constant
u2 length; // must be 4.
s4 value; // CRC32 value of transitions
}
See ZoneInfo.checksum .

1.7 gmtoffsetwillchange structure

This record has a flag value for ZoneInfo#rawOffsetWillChange . If this record is not present in a zoneinfo file, 0 is assumed for the value.

gmtoffsetwillchange {
u1 tag; // 0x07 : constant
u2 length; // must be 1.
u1 value; // 1: if the GMT raw offset will change
// in the future, 0, otherwise.
}

2. ZoneInfoMappings file

The ZoneInfoMappings file consists of the following members.

ZoneInfoMappings {
u1 magic[7];
u1 version;
SET OF {
versionName version;
zone_id_table zoneIDs;
raw_offset_table rawoffsets;
raw_offset_index_table rawoffsetindices;
alias_table aliases;
excluded_list excludedList;
}
}
magic is a byte-string constant which has the file type. This field must be "javazm\0" defined as #JAVAZM_LABEL .

version is the version number of this file format. This will be used for compatibility check. This field must be 0x01 in this version.

versionName shows which version of Olson's data has been used to generate this ZoneInfoMappings. (e.g. tzdata2000g)
This field is for trouble-shooting and isn't usually used in runtime.

zone_id_table, raw_offset_index_table and alias_table are general information of supported zones.

2.1 zone_id_table structure

The list of zone IDs included in the zi database. The list does not include zone IDs, if any, listed in excludedList.

zone_id_table {
u1 tag; // 0x40 : constant
u2 length; // byte length of whole values
u2 zone_id_count;
zone_id value[zone_id_count];
}

zone_id {
u1 byte_length; // byte length of id
u1 id[byte_length]; // zone name string
}

2.2 raw_offset_table structure


raw_offset_table {
u1 tag; // 0x41 : constant
u2 length; // byte length of whole values
s4 value[length/4]; // raw GMT offset in milliseconds
}

2.3 raw_offset_index_table structure


raw_offset_index_table {
u1 tag; // 0x42 : constant
u2 length; // byte length of whole values
u1 value[length];
}

2.4 alias_table structure


alias_table {
u1 tag; // 0x43 : constant
u2 length; // byte length of whole values
u2 nentries; // number of id-pairs
id_pair value[nentries];
}

id_pair {
zone_id aliasname;
zone_id ID;
}

2.5 versionName structure


versionName {
u1 tag; // 0x44 : constant
u2 length; // byte length of whole values
u1 value[length];
}

2.6 excludeList structure

The list of zone IDs whose zones will change their GMT offsets (a.k.a. raw offsets) some time in the future. Those IDs must be added to the list of zone IDs for getAvailableIDs(). Also they must be examined for getAvailableIDs(int) to determine the current GMT offsets.

excluded_list {
u1 tag; // 0x45 : constant
u2 length; // byte length of whole values
u2 nentries; // number of zone_ids
zone_id value[nentries]; // excluded zone IDs
}
Field Summary
public static final  byte[] JAVAZI_LABEL    The magic number for the ZoneInfo data file format. 
public static final  byte JAVAZI_VERSION    The ZoneInfo data file format version number. Must increase one when any incompatible change has been made. 
public static final  byte TAG_RawOffset    Raw offset data item tag. 
public static final  byte TAG_LastDSTSaving    Known last Daylight Saving Time save value data item tag. 
public static final  byte TAG_CRC32    Checksum data item tag. 
public static final  byte TAG_Transition    Transition data item tag. 
public static final  byte TAG_Offset    Offset table data item tag. 
public static final  byte TAG_SimpleTimeZone    SimpleTimeZone parameters data item tag. 
public static final  byte TAG_GMTOffsetWillChange    Raw GMT offset will change in the future. 
public static final  String JAVAZM_FILE_NAME    The ZoneInfoMappings file name. 
public static final  byte[] JAVAZM_LABEL    The magic number for the ZoneInfoMappings file format. 
public static final  byte JAVAZM_VERSION    The ZoneInfoMappings file format version number. Must increase one when any incompatible change has been made. 
public static final  byte TAG_ZoneIDs    Time zone IDs data item tag. 
public static final  byte TAG_RawOffsets    Raw GMT offsets table data item tag. 
public static final  byte TAG_RawOffsetIndices    Indices to the raw GMT offset table data item tag. 
public static final  byte TAG_ZoneAliases    Time zone aliases table data item tag. 
public static final  byte TAG_TZDataVersion    Olson's public zone information version tag. 
public static final  byte TAG_ExcludedZones    Excluded zones item tag. (Added in Mustang) 
Method from sun.util.calendar.ZoneInfoFile Summary:
addToCache,   getCustomTimeZone,   getExcludedZones,   getFileName,   getFromCache,   getRawOffsetIndices,   getRawOffsets,   getZoneAliases,   getZoneIDs,   getZoneInfo,   toCustomID
Methods from java.lang.Object:
equals,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from sun.util.calendar.ZoneInfoFile Detail:
 static synchronized ZoneInfo addToCache(String id,
    ZoneInfo zi) 
 public static ZoneInfo getCustomTimeZone(String originalId,
    int gmtOffset) 
    Gets a ZoneInfo with the given GMT offset. The object has its ID in the format of GMT{+|-}hh:mm.
 static List getExcludedZones() 
 public static String getFileName(String ID) 
    Converts the given time zone ID to a platform dependent path name. For example, "America/Los_Angeles" is converted to "America\Los_Angeles" on Win32.
 static synchronized ZoneInfo getFromCache(String id) 
 static byte[] getRawOffsetIndices() 
 static int[] getRawOffsets() 
 static Map getZoneAliases() 
 static List getZoneIDs() 
 public static ZoneInfo getZoneInfo(String id) 
 public static String toCustomID(int gmtOffset)