Sun Java SE TZupdater tool


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." The US2007DST data changes  were incorporated into the
following releases: 1.3.1_18, 1.4.2_11, 5.0u7.

Sun  recommends utilizing the latest Sun  Java SE 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 Sun
JDK/JRE update  release, this tool  provides a  route  of updating timezone
data while leaving other system configuration and dependencies unchanged.


System Requirements

The tool supports Sun's JDK/JRE   1.4.0  and later releases (1.4.0,   1.4.1
1.4.2, 5.0, and 6),  all updates of  those releases, and on all supported
platforms.  The java.vendor property value must be "Sun Microsystems Inc.".


Installation

Download the tool bundle archive tzupdater-tzdata2006p-b03.zip from the Sun
Java SE download site at http://java.sun.com/javase/downloads/index.jsp


Usage

The tzupdater tool modifies the JDK/JRE image used to execute the tool.

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.

The command line interface is as follows:   java -jar tzupdater.jar options

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 numbers
                of the JRE and the archive embedded in the jar file and
                exit.

-u, --update    Update  the  time   zone  data  and   perform verification
                tests. The  verification tests can  be run separately with
                the -t option. If this option is specified  with -h, -t or
                -V option,  the command displays the   usage to stdout and
                exits.

-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.  Not
                needed under normal operating conditions.

-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. This
                option must be specified with the -u, -f or -t option.

                A few  time zone  IDs in JDK  1.1  and the Olson  time zone
                database IDs   (industry   standard  IDs)  conflict.    The
                conflicting time zone IDs are "EST",  "MST" and "HST" as of
                this release. If these IDs  are used in your  applications,
                the  -bc option needs to be   specified. See also Sun's bug
                6466476.

-t, --test      Runs verification tests only and exit.  If the JRE has time
                zone data  that doesn't  match the one    in the tool,  the
                verification tests report errors and  fail.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.


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.

   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. The complete
      support  of all time zone  display names requires installation of the
      latest Sun Java SE JDK/JRE update release.

   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.

    Software Package Management errors

       The   current tzupdater tool  works  outside of the native operating
       environment  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  tzupdater.     These are files  under    the  jre/lib/zi
       directory.

    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
           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.tzdata2006p" 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.





