Timezone Updater Tool


By the Java SE Platform Support Team, June 2014
Contents


Introduction

The TZUpdater tool is provided to allow you to update installed Java Development Kit (JDK) and Java Runtime Environment (JRE) software with more recent timezone data, to accommodate daylight saving time (DST) changes in different countries.

Oracle relies on the timezone data publicly available through IANA's Time Zone Database.  Updates to the TZUpdater tool can be expected within a few weeks after IANA releases an update to the Time Zone Database.  Updates might be released sooner f the urgency of the time zone change requires it.

Oracle recommends that you use the latest Oracle Java SE platform JDK or JRE update release as the preferred means of delivering both timezone data updates and other product improvements, such as security fixes. To see which JDK or JRE update release incorporates the updated timezone data for your locale, see Timezone Data Versions in the JRE Software. However, if you are unable to use Oracle's latest JDK or JRE update release or if the timezone data on the latest release is not the most current one available, the TZUpdater tool provides a means of updating timezone data while leaving other system configuration and dependencies unchanged.

System Requirements

The TZUpdater tool supports all currently supported versions of the Oracle JDK and JRE, on all supported platforms.The java.vendor property value must be Sun Microsystems Inc.  or Oracle Corporation or BEA Systems,Inc.

If you have already run a previous version of the TZUpdater tool on your JDK/JRE software, you do not need to apply this version of the tool, unless your system requires the specific bug fixes described in Timezone Data Versions in the JRE Software.

Download

A version of TZUpdater tool for updating the current version of Oracle’s Java Runtime Enviroment is available in Oracle Technology Network - Java SE Download Page

Support customers can download a TZUpdater tool for older versions through My Oracle Support. See Note 1412103.2
 

Usage

The TZUpdater tool modifies the JDK/JRE software instance that is used to execute the tool. A single image of the JDK/JRE software is modified per execution. To administer the tool to multiple instances of the JDK/JRE software, see the section Systemwide Usage.

You must stop any running instances of the JDK/JRE software to be operated upon before you run the TZUpdater tool on that installed JDK/JRE software image.

Run the TZUpdater tool with the following command:

java -jar tzupdater.jar  
                    
options
 

To update timezone data successfully, you should ensure that you have sufficient privileges to modify the JDK_HOME /jre/lib or JRE_HOME /lib directory. If you do not have sufficient priviledges to modify these directories, contact your system administrator.

Options

If you do not specify any options, the usage message is displayed. To update the timezone data, specify either the -u or -f option.

Option
Description
-h, --help
Print the usage to stdout and exit. Other options are ignored if you specify this option.
-V, --version
Show the tool version number and the tzdata version numbers of the JRE software and the archive embedded in the JAR file and exit.
-u, --update
Update the time zone data and perform verification tests. You can run the verification tests separately with the -t option. If you specify the -h, -t, or -V options, the command displays the usage to stdout and exits.
-f, --force
Force update the tzdata even if the version of the tzdata archive is older than the JRE software's tzdata version. This option does not require the -u option to perform the update. This option is not needed under normal operating conditions.
-v, --verbose
Display detailed messages to stdout.
-bc, --backwardcompatible
Keep backward compatibility with the JDK version 1.1 three-letter timezone IDs, "MST," EST,"and "HST." Any timezone IDs that conflict with the JDK version 1.1 timezone IDs will be removed from the installed timezone data. You must specify the -bc option with the -u, -f or -t option.
-t, --test
Run verification tests only and exit. If the JRE has timezone data that does not match the data in the tool, the verification tests report errors and fail. The -f option is ignored if specified. If you specify the -bc option, any test cases for timezone IDs that conflict with the JDK version 1.1timezone IDs will be ignored.
 
Error Handling

The tool tries to restore the original state when it has encountered an unexpected error, such as lack of disk space.

 
Known Restrictions

The tool has a few restrictions due to the TimeZone API and implementation constraints.

  • Conflict between timezone IDs in JDK version 1.1 and timezone IDs used in Olson tzdata2005r
     
    There is a conflict between certain three-letter timezone IDs in JDK version 1.1 and the timezone database IDs used in Olson tzdata2005r or later versions. The conflicting timezone IDs are "EST," "MST," and "HST." If your applications use these IDs, then they will incorrectly calculate daylight savings time for these timezone IDs. To resolve this issue, you must run the TZUpdater tool and specify the -f -bc options. See Sun Alert 102836 for Java and Background Overview on Sun Alert 102836.
     
  • Timezone display names
     
    This tool will not update display names of timezones that are completely new or have display name-related changes. Full support of all timezone display names requires installation of the latest Oracle Java SE platform JDK/JRE update release.
     
  • Systemwide Usage
     
    You must stop any running instances of the JDK/JRE software to be operated upon before you run the TZUpdater tool on that installed JDK/JRE software image.
     
    It is possible for systems to accrete multiple copies of JDK/JRE software images, so you might need to apply the tool individually to each JDK/JRE software image. Locating multiple installed copies of the JDK/JRE software on Unix derivative systems is shown below. Microsoft Windows users can use the desktop search utility.
     
    1. Find locally installed JDK/JRE software instances for Unix derived systems:
       
      /usr/bin/find  
                                  
      DIRPATH
      -fstype nfs -prune -o -fstype autofs -prune -o -name java -print -exec {} -version \;
       
      Where DIRPATH is a directory path to search under for installed instances of the Java SE platform, for example, /usr.
       
    2. Automate updating of locally installed instances:
       
      /usr/bin/find  
      
      DIRPATH
      -fstype nfs -prune -o -fstype autofs -prune -o -name java -print -exec {} -jar /
      ABSOLUTEPATH
      /tzupdater.jar -u \;
       
      Where DIRPATH is a directory path to search under for installed instances of the Java SE platform, for example, /usr. ABSOLUTEPATH should be replaced with the full path name to the directory into which tzupdater.jar is expanded.
       
  • Restrictive umask settings on Solaris
     
    The TZUpdater tool creates files with default file permissions. On the Solaris operating system, this is taken from the umask. A default umask of 022 should be used for running the TZudpater tool. A more restrictive umask such as umask 077 will mean files created by the tool are unreadable by other users.
System-Specific Installation Information

TZUpdater is a pure Java tool that does not address platform-specific software management issues.  For example, on a Windows system, this means that the additional and backup files created by the tool will not be removed during an uninstall. To uninstall updated JRE software, check the JRE software's install directory and remove it manually once the uninstaller completes.

For Solaris systems, where the JRE software being updated exists as a Solaris package (such as in /usr/j2se or /usr/jdk/ instances), this has meant that the pkgchk command would highlight the changes as errors or inconsistencies. Starting with version 1.1.0 of TZUpdater, the tool runs an additional series of package management commands that updates the package database where appropriate.

On a Solaris 10 system where existing package-based JRE software has been updated by the initial release of TZUpdater, and zones have been created, the zones will contain the same pkgchk errors as the global zone. During zone creation, these pkgchk errors will be highlighted at the end of the zone installation command.

To resolve Solaris package database errors, take the following steps. However, if you are not running on a Solaris 10 system or your system does not have zones, only step 1 is required.  If the system is a Solaris 10 system with additional zones, run step 1 only in the global zone and follow steps 2 and 3.

  1. Run the current version of TZUpdater, with the -f force option to reapply the timezone update to a previously updated JRE software instance. The update will take place, and the additional package resolution commands will be executed. The update must be executed as the root user and is relevant to the global zone only in a Solaris 10 system.

  2. For systems with zones, unpack the pkg_resolve.sh script from the tzupdater.jar file :
    /bin/jar xf tzupdater.jar pkg_resolve.sh
    
     
  3. In the zones where there is a package-based Java platform installation, execute the script. You must run the script as root:
    /bin/ksh ./pkg_resolve.sh  
                            
    JAVA_PATH
     
    For example:
    /bin/ksh ./pkg_resolve.sh /usr/jdk/instances/jdk1.5.0/bin/java
    
     

NOTE: The update to the package system removes many files from the package database and reinserts them, so it can take up to 15 minutes.

Removing TZUpdater Tool Changes

You must stop any running instances of the JDK/JRE software to be operated upon before you run the TZUpdater tool on that installed JDK/JRE software image.

There is currently no option to remove TZUpdater modifications. By following the following steps, you can manually remove the modifications made by the current TZUpdater tool.

For JDK 7 and earlier family versions:

  • Locate the 'zi' directory under the modified JAVAHOME/jre/lib directory. This is the newer data file.
  • Locate a 'zi.tzdata*' directory in the same JAVAHOME/jre/lib directory. This is the replaced, older data.
  • Obtain the currently installed timezone data version from the command java -jar tzupdater.jar -V.
  • Rename the current 'zi' directory to something like 'zi.tzdata2007g', or whatever version was given by the command in step 3. Ensure this does not conflict with the older data directory.
  • Rename the older data directory to 'zi'.
  • Validate the change in currently active timezone data by executing java -jar tzupdater.jar -V.
  • Restart applications on this JDK/JRE instance as desired.

For JDK 8 and later family versions:

  • Locate the 'tzdb.dat' file under the modified JAVAHOME/jre/lib directory. This is the newer data file.
  • Locate the 'tzdb.dat.<oldtzdataversion>'; file in the same JAVAHOME/jre/lib directory. This is the replaced, older data file.
  • Obtain the currently installed timezone data version from the command java -jar tzupdater.jar -V.
  • Rename the current 'tzdb.dat' file to something like 'tzdb.dat.<newtzdataversion>', or whatever version was given by the command in step 3. Ensure this name does not conflict with the older data files.
  • Rename the older data file to 'tzdb.dat'.
  • Validate the change in currently active timezone data by executing java -jar tzupdater.jar -V.
  • Restart applications on this JDK/JRE instance as desired.
For More Information

The following links point to information provided by Oracle Corporation relating to timezones and DST changes and how they affect the Java platform and other Oracle products:

The following external links provide general information about timezones and DST:

Left Curve
Java SDKs and Tools
Right Curve
Left Curve
Java Resources
Right Curve
VTS OnDemand RHS Banner



Duke's Choice RHS Banner

JavaOne 2014 Replay banner