Diagnostics Guide

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Oracle JRockit Time Zone Updater

The Oracle JRockit Time Zone Updater (TZUpdater) allows you to update installed JDK/JRE images with more recent time zone data to accommodate the U.S. 2007 daylight saving time changes (US2007DST) originating with the U.S. Energy Policy Act of 2005.

Oracle recommends using the latest Oracle JRockit JDK release as the preferred vehicle for delivering both time zone data updates and other product improvements, such as security fixes. If you are unable to use the latest JRockit JDK/JRE update release, this tool provides a route of updating time zone data while leaving other system configuration and dependencies unchanged.

This section contains information on the following subjects:

 

Downloading the TZUpdater

Download the TZUpdater from:

http://www.oracle.com/technology/software/products/jrockit/index.html

 

Introduction to the TZUpdater

To upgrade a specific Java installation, you need to include the full path to the Java executable of that installation. If tzupdater.jar is run by just running java -jar..., or by double-clicking the tzupdater.jar file, this will invoke Sun’s Java on many systems, which will result in an error message being displayed. The section Example of the Default way of Using TZUpdater explains the typical use of TZUpdater.

A single JDK/JRE image is modified per execution. For administering of multiple JDK/JRE instances, see System-wide Usage.

Prior to running the TZUpdater, you need to stop any running instances of the specific JDK/JRE that you will operate upon.

The TZUpdater modifies and updates the JVM it is run with, thus it is important to run the tool as a command-line application, see Command-line Options Described.

 

System Requirements to Run the TZUpdater

The TZUpdater supports Oracle’s JDK/JRE releases 1.4 or later on all supported platforms.

 

Using the TZUpdater

The command-line interface is the following:

JAVA_HOME/bin/java -jar tzupdater.jar options

Command-line Options Described

If no command-line option is specified, the usage message is displayed. To perform time zone data update, either the -u or -f option must be specified, see Table 22-1 for a list of all available command line options.

Table 22-1 List of available options.
Command
Option Name
Description
-h
help
Prints the usage to stdout and exit. Other options are ignored if specified.
-V
version
Shows the tool version number and the tzdata version numbers of the JRE and the archive embedded in the jar file and exit.
-u
update
Updates the time zone data. If this option is specified with -h, -t, or -V option, the command displays the usage to stdout and exit.
-f
force
Force update the tzdata even if the version of the tzdata archive is older then the JRE’s tzdata version. This option doesn’t require the -u option to perform the update.
-v
verbose
Displays detailed messages to stdout.
-bc
backward compatible
Keeps backward compatibility with the 3-letter time zone IDs of JDK 1.1. Any time zone IDs that conflict with the JDK 1.1 time zone IDs will be removed from the installed time zone data. See Known Issues for details. This option must be specified with the -u, -f, or -t option.
-t
test
Runs verification tests only and exit. The -f option is ignored if specified. If the -bc option is specified, any test cases for time zone IDs that conflict with the JDK 1.1 time zone IDs will be ignored.

Example of the Default way of Using TZUpdater

Below is an example of the default way of using the TZUpdater to upgrade time zone data on a Java installation at, for example, /opt/bea/jrockit90_150_06.

  1. Test the current version of the timezone data of the JRE:

    2. > /opt/bea/jrockit90_150_06/bin/java -jar tzupdater.jar -V

    tzupdater version: 1.0.0-b03
    JRE time zone data version: tzdata2005n
    Embedded time zone data version: tzdata2007a

  2. Update the timezone data:

    3. > /opt/bea/jrockit90_150_06/bin/java -jar tzupdater.jar -u

  3. Verify that the version is updated:

    4. > /opt/bea/jrockit90_150_06/bin/java -jar tzupdater.jar -V

    tzupdater version: 1.0.0-b03
    JRE time zone data version: tzdata2007a
    Embedded time zone data version: tzdata2007a

  4. Run the built in tests to test the new timezone data. If nothing is printed the tests has succeeded.

    5. > /opt/bea/jrockit90_150_06/bin/java -jar tzupdater.jar -t

 

Error Handling

The TZUpdater tries to restore the original state when it has encountered an unexpected error, such as lack of disk space. Such errors will generate a TzRuntimeException.

 

System-wide Usage

Stop any running instances of the JDK/JRE that you will operate on before running the TZUpdater for that JDK/JRE.

It is possible for systems to accrete multiple copies of JDK/JRE images, so you might need to apply the tool individually to each JDK/JRE image. Microsoft Windows users can use the desktop search utility to find each image. To locate multiple installed copies of the JDK/JRE on a UNIX derivative system, follow these steps:

  1. Find locally installed JDK/JRE instances for UNIX derived systems:

    2. /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 for installed Java SE instance, for example, /usr.

  2. Automate updating of locally installed instances:

    3. /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 for installed Java SE instance, for example, /usr. Replace ABSOLUTEPATH with the full pathname to the directory where tzupdater.jar is expanded.\

 

Determining Your TZUpdater Version

Use the command tzinfo to see which version of TZUpdater you’re using. Enter the command from your JRockit JDK installation directory’s bin\ directory. The system will respond with complete version information; for example, if you entered: 

\jrockits\R27.3.0_R27.3.0-45_1.5.0\bin\tzinfo
The system would respond:
java version "1.5.0_10"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_10-b03)
BEA JRockit(R) (build R27.3.0-45-79733-1.5.0_10-20070330-1521-windows-ia32, 
compiled mode)
Time zone data version: tzdata2006k

 

Removing TZUpdater Changes

Stop any running instances of the JDK/JRE that you will operate on before running the TZUpdater for that JDK/JRE.

The modifications the current TZUpdater results in can only be manually removed by following these steps:

  1. Locate the zi directory under the modified JAVAHOME/jre/lib directory. This is the newer data.
  2. Locate a zi.tzdata* directory in the same JAVAHOME/jre/lib directory. This is the replaced, older data.
  3. Obtain the currently installed timezone data version from the command java -jar tzupdater.jar -V.
  4. Rename the current zi directory to something like “zi.tzdata2007a” or whatever the version command in step 3 gave. Make sure that this renaming does not conflict with the older data directory.
  5. Rename the older data directory to zi.
  6. Validate the change in the currently active timezone data by executing java -jar tzupdater.jar -V.
  7. Restart your applications on the updated JDK/JRE instance.

 

Known Issues

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

Table 22-2 Known issue in the TZUpdater.
Issue
Explanation of the known issue
Time zone display names
This tool will not update time zone display names of time zones that are completely new or have display name related changes. An example is that Europe/Podgorica is a new time zone ID in tzdata2006n due to the Serbia/Montenegro split. Another example is that America/Indiana/Knox changed from Eastern Time to Central Time on April 2, 2006, which change appeared since tzdata2006a. The time zone display names for America/Indiana/Knox were changed in Java version 5.0 update 8.
JDK 1.1 time zone ID compatibility
In tzdata2005r, the Olson time zone database added EST, MST, and HST with no DST rules (i.e., standard time only). These IDs conflict with the same IDs in JDK 1.1. When users need the JDK 1.1 compatible time zone IDs rather than the complete set of the Olson time zone IDs, these incompatible IDs need to be removed. See also Sun's bug 6466476.
TimeZone.getAvailableIds(int) and TimeZone.getRawOffset() limitation and JCK
These TimeZone methods do not take a time stamp based on the API design assumption that a time zone’s GMT offset never changes. Therefore, it is not possible to keep their return values consistent all the time. There is JCK test case TimeZone2014 that the return values of these methods are consistent. This test case fails if and only if there are any time zones of which GMT offsets will change in future time.
A workaround fix was added to Java 5.0 update 4 and 6 Standard Edition, which involved a time zone data file format change. Therefore, two versions of time zone data archives need to be provided with the tool in case that a future GMT offset change is involved in any time zones.
See Sun’s bug 5055567 for details.

Note: The JCK test case fails without the 5055567 fix until the actual GMT offsets transition occurs.
Software Package Management errors
The current TZUpdater works outside of the native operating environment software package management infrastructure. Once you have used TZUpdater to install newer time zone data files, commands such as Solaris pkgchk will report errors concerning the files altered by TZUpdater. These are files under the jre/lib/zi directory.


  Back to Top       Previous  Next