BEA JRockit TZUpdater Tool



Important
       This  tool  will  modifiy and update the JVM it is run with, it is thus
       important to run the tool as a command line  application  per  instruc-
       tions described below.


Introduction
       The  tzupdater  tool  is  provided  to  allow the updating of installed
       JDK/JRE images with more recent timezone data in  order  to  accomodate
       the U.S. 2007 daylight saving time changes (US2007DST) originating with
       the U.S. Energy Policy Act of 2005.

       While BEA recommends utilizing the latest BEA  JRockit  JDK/JRE  update
       release  as  the  preferred  vehicle  for delivering both timezone data
       updates and other product improvements such as security fixes;  if  the
       end-user  or  system-administrator  is unable to use the latest JRockit
       JDK/JRE update release, this tool provides a route of updating timezone
       data   while   leaving  other  system  configuration  and  dependencies
       unchanged.

       Additional information can be found on
       http://edocs.bea.com/jrockit/geninfo/diagnos/tzupdate.html


System Requirements
       The tool supports BEA's JDK/JRE releases 1.4 or later, and on all  sup-
       ported  platforms. The java.vendor property value must be "BEA Systems,
       Inc.".



Usage
       The command line interface is as follows:

       [Path_to_java_installation/]java -jar tzupdater.jar options


   Description
       The tzupdater tool upgrades the timezone data of the JRE that runs  it.
       To  upgrade  a specific java installation, it is recommended to include
       the full path to the java executable of  that  installation.  If  tzup-
       dater.jar  is run by just running "java -jar ...", or by doubleclicking
       the tzupdater.jar file, this will invoke Sun's  java  on  many  systems
       which  will  result  in  an error message being displayed. See examples
       bellow for the typical use of tzupdater.

       A single JDK/JRE image is modified per execution. For administering  to
       multiple JDK/JRE instances, read below under "System-wide Usage".

       Any  executing  instances  of  the  JDK/JRE to be operated upon must be
       stopped prior to running the  tzupdater  tool  against  that  installed
       JDK/JRE on-disk image.


   Options
       If no options are specified, the usage message is displayed. To perform
       time zone data update, either the -u or -f option must be specified.


       -h, --help     Print the usage to stdout and exit.  Other  options  are
                      ignored if specified.

       -V, --version  Show the tool version number and the tzdata version num-
                      bers of the JRE and the archive embedded in the jar file
                      and exit.


       -u, --update   Update  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 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  Display detailed messages to stdout.


       -bc, --backwardcompatible
                      Keep 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 the known restriction section 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.



Examples
       This would be the default way of using tzupdater  to  upgrade  timezone
       data on a java installation at /opt/bea/jrockit90_150_06

       Test the current version of the timezone data of the JRE

          > /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

       Update the timezone data

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

       Verify that the version is updated

          > /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

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

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



Error Handling
       The tool 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
       Any executing instances of the JDK/JRE to  be  operated  upon  must  be
       stopped  prior  to  running  the  tzupdater tool against that installed
       JDK/JRE on-disk image.

       It is possible for  systems  to  accrete  multiple  copies  of  JDK/JRE
       images,  so one may need to apply the tool individually to each JDK/JRE
       image. Locating multiple  installed  copies  of  the  JDK/JRE  on  Unix
       derivative  systems is shown below. Microsoft Windows users can use the
       desktop search utility.


   (1) Find locally installed JDK/JRE 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 Java SE
       instance, for instance /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 Java SE
       instance, for instance /usr.  ABSOLUTEPATH should be replaced with  the
       full pathname to the directory where tzupdater.jar is expanded into.



Removing tzupdater Tool Changes
       Any  executing  instances  of  the  JDK/JRE to be operated upon must be
       stopped prior to running the  tzupdater  tool  against  that  installed
       JDK/JRE on-disk image.

       There does not currently exist a tzupdater modification removal option.
       The modifications the current tzupdater tool results in can be manually
       removed by following these steps:


       1. Locate  the  zi directory under the modified JAVAHOME/jre/lib direc-
          tory. This is the newer data.

       2. Locate a zi.tzdata* directory in the  same  JAVAHOME/jre/lib  direc-
          tory. This is the replaced, older data.

       3. Obtain  the  currently installed timezone data version from the com-
          mand '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. Insure this does not
          conflict with the older data directory.

       5. Rename the older data directory to zi.

       6. Validate the change in currently active timezone data  by  executing
          'java -jar tzupdater.jar -V'.

       7. Restart applications on this JDK/JRE instance as desired.



Known Restrictions
       The tool has a few restrictions due to the TimeZone API and implementa-
       tion constraints.


   1. 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 1.5.0_08.


   2. 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.


   3. TimeZone.getAvailableIds(int) and TimeZone.getRawOffset() limitation and
       JCK
       These  TimeZone methods don't take a time stamp based on the API design
       assumption that a time zone's GMT offset never changes. Therefore, it's
       not  possible  to  keep  their  return  values consistent all the time.
       There's 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 1.5.0_4 and 1.6.0, 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  that  the  JCK  test case fails without the 5055567 fix
       until the actual GMT offsets transition occurs.


   4. Software Package Management errors
       The current tzupdater tool works outside of the native operating  envi-
       ronment  software  package  management  infrastructure. Once users have
       used tzupdater to install newer timezone data files, commands  such  as
       Solaris pkgchk will report errors concerning the files altered by tzup-
       dater. These are files under the jre/lib/zi directory.
