sun.util.calendar

Class ZoneInfoFile

java.lang.Object

sun.util.calendar.ZoneInfoFile

public class ZoneInfoFile
extends java.lang.Object

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
   }
 

Since:

1.4

Field Summary

Fields

Modifier and Type	Field and Description
static byte[]	JAVAZI_LABEL The magic number for the ZoneInfo data file format.
static byte	JAVAZI_VERSION The ZoneInfo data file format version number.
static java.lang.String	JAVAZM_FILE_NAME The ZoneInfoMappings file name.
static byte[]	JAVAZM_LABEL The magic number for the ZoneInfoMappings file format.
static byte	JAVAZM_VERSION The ZoneInfoMappings file format version number.
static byte	TAG_CRC32 Checksum data item tag.
static byte	TAG_ExcludedZones Excluded zones item tag.
static byte	TAG_GMTOffsetWillChange Raw GMT offset will change in the future.
static byte	TAG_LastDSTSaving Known last Daylight Saving Time save value data item tag.
static byte	TAG_Offset Offset table data item tag.
static byte	TAG_RawOffset Raw offset data item tag.
static byte	TAG_RawOffsetIndices Indices to the raw GMT offset table data item tag.
static byte	TAG_RawOffsets Raw GMT offsets table data item tag.
static byte	TAG_SimpleTimeZone SimpleTimeZone parameters data item tag.
static byte	TAG_Transition Transition data item tag.
static byte	TAG_TZDataVersion Olson's public zone information version tag.
static byte	TAG_ZoneAliases Time zone aliases table data item tag.
static byte	TAG_ZoneIDs Time zone IDs data item tag.

Constructor Summary

Constructors

Constructor and Description
ZoneInfoFile()

Method Summary

Methods

Modifier and Type	Method and Description
static ZoneInfo	getCustomTimeZone(java.lang.String originalId, int gmtOffset) Gets a ZoneInfo with the given GMT offset.
static java.lang.String	getFileName(java.lang.String ID) Converts the given time zone ID to a platform dependent path name.
static ZoneInfo	getZoneInfo(java.lang.String id)
static java.lang.String	toCustomID(int gmtOffset)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

JAVAZI_LABEL

public static final byte[] JAVAZI_LABEL

The magic number for the ZoneInfo data file format.

JAVAZI_VERSION

public static final byte JAVAZI_VERSION

The ZoneInfo data file format version number. Must increase one when any incompatible change has been made.

See Also:

Constant Field Values

TAG_RawOffset

public static final byte TAG_RawOffset

Raw offset data item tag.

See Also:

Constant Field Values

TAG_LastDSTSaving

public static final byte TAG_LastDSTSaving

Known last Daylight Saving Time save value data item tag.

See Also:

Constant Field Values

TAG_CRC32

public static final byte TAG_CRC32

Checksum data item tag.

See Also:

Constant Field Values

TAG_Transition

public static final byte TAG_Transition

Transition data item tag.

See Also:

Constant Field Values

TAG_Offset

public static final byte TAG_Offset

Offset table data item tag.

See Also:

Constant Field Values

TAG_SimpleTimeZone

public static final byte TAG_SimpleTimeZone

SimpleTimeZone parameters data item tag.

See Also:

Constant Field Values

TAG_GMTOffsetWillChange

public static final byte TAG_GMTOffsetWillChange

Raw GMT offset will change in the future.

See Also:

Constant Field Values

JAVAZM_FILE_NAME

public static final java.lang.String JAVAZM_FILE_NAME

The ZoneInfoMappings file name.

See Also:

Constant Field Values

JAVAZM_LABEL

public static final byte[] JAVAZM_LABEL

The magic number for the ZoneInfoMappings file format.

JAVAZM_VERSION

public static final byte JAVAZM_VERSION

The ZoneInfoMappings file format version number. Must increase one when any incompatible change has been made.

See Also:

Constant Field Values

TAG_ZoneIDs

public static final byte TAG_ZoneIDs

Time zone IDs data item tag.

See Also:

Constant Field Values

TAG_RawOffsets

public static final byte TAG_RawOffsets

Raw GMT offsets table data item tag.

See Also:

Constant Field Values

TAG_RawOffsetIndices

public static final byte TAG_RawOffsetIndices

Indices to the raw GMT offset table data item tag.

See Also:

Constant Field Values

TAG_ZoneAliases

public static final byte TAG_ZoneAliases

Time zone aliases table data item tag.

See Also:

Constant Field Values

TAG_TZDataVersion

public static final byte TAG_TZDataVersion

Olson's public zone information version tag.

See Also:

Constant Field Values

TAG_ExcludedZones

public static final byte TAG_ExcludedZones

Excluded zones item tag. (Added in Mustang)

See Also:

Constant Field Values

Constructor Detail

ZoneInfoFile

public ZoneInfoFile()

Method Detail

getFileName

public static java.lang.String getFileName(java.lang.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.

Returns:

a modified ID replacing '/' with File.separatorChar if needed.

getCustomTimeZone

public static ZoneInfo getCustomTimeZone(java.lang.String originalId,
                         int gmtOffset)

Gets a ZoneInfo with the given GMT offset. The object has its ID in the format of GMT{+|-}hh:mm.

Parameters:

originalId - the given custom id (before normalized such as "GMT+9")

gmtOffset - GMT offset in milliseconds

Returns:

a ZoneInfo constructed with the given GMT offset

toCustomID

public static java.lang.String toCustomID(int gmtOffset)

getZoneInfo

public static ZoneInfo getZoneInfo(java.lang.String id)

Returns:

a ZoneInfo instance created for the specified id, or null if there is no time zone data file found for the specified id.