Name: vi73552 Date: 05/04/99


The JDK 1.1 API documentation does not reflect either
the JLS specification or JDK's 1.1 actual implementation of
java.util.Date.getTimezoneOffset().

[ _emphasis_ added ]

The JDK 1.1 API documentation says:

    Returns the local time-zone offset. The time-zone offset
    is the number of minutes that must be _added_ to GMT to give
    the local time zone. This value includes the correction,
    if necessary, for daylight saving time.

The JLS says:

   21.3.29 public int getTimezoneOffset()

   This method returns the offset, measured in minutes, for
   the local time zone relative to UTC that is appropriate
   for the time represented by this Date object.

   For example, in Massachusetts, five time zones
   west of Greenwich:

   new Date(96, 1, 14).getTimezoneOffset() returns 300

   because on February 14, 1996, standard time
   (Eastern Standard Time) is in use, which is
   offset five hours from UTC; but:

   new Date(96, 5, 1).getTimezoneOffset() returns 240

   because on May 1, 1996, daylight saving time
   (Eastern Daylight Time) is in use, which is offset
   only four hours from UTC.

JDK 1.1 is currently implemented according to the example in the
the JLS (even though the JLS specification itself is ambiguous)
and therefore the JDK 1.1 API documentation is in conflict with
both the JLS and the JDK 1.1 implementation.

Therefore, the JDK 1.1 API documentation _SHOULD_ say:

    Returns the local time-zone offset. The time-zone offset
    is the number of minutes that must be _subtracted_ from GMT
    to give the local time zone. This value includes the
    correction, if necessary, for daylight saving time.

Note: I realise this API is deprecated. However, it would still
be useful if the API documentation reflected the actual and
intended behaviour of the API rather than something different
from this behaviour.
(Review ID: 57187)
======================================================================