A DESCRIPTION OF THE PROBLEM :

The javadoc for java.sql.Timestamp can be confusing.  The class desciption states that "only integral seconds are stored in the
java.util.Date component."  However, the description of getTime() claims that the method "returns the number of milliseconds ... represented by this Timestamp  customer ."  Many people do not believe that milliseconds are "integral" seconds.

As a result, some users believe that the code given below should return

The values are NOT equal
sv: 767676767676
sv2: 767676767000

instead of

The values are equal
sv: 767676767676
sv2: 767676767676


---------- BEGIN SOURCE ----------
import java.sql.Timestamp;

public class LongValueTest
{
	public static void main(String[] args)
	{
		long sv = 767676767676L;
		Timestamp time = new Timestamp(sv);
		long sv2 = time.getTime();
		if (sv == sv2)
		{
			System.out.println("The values are equal");
		}
		else
		{
			System.out.println("The values are NOT equal");
		}
		System.out.println("sv: "+sv);
		System.out.println("sv2: "+sv2);
	}
}
---------- END SOURCE ----------
(Review ID: 145942) 
======================================================================

JDK 1.3.x did not return the milliseconds portion of the time.  In other words, the test case would result in

The values are NOT equal
sv: 767676767676
sv2: 767676767000

with JDK 1.3.1.

(Review ID: 146854) 

N/A

We have gone to great lengths to reduce user confusion in this 
area in JDK 1.4.1. I believe additional documantation and notes
supplied within the API should assist greatly here.

  xxxxx@xxxxx   2002-06-05

The code DOES return:

The values are NOT equal
sv: 767676767676
sv2: 767676767000

For jdk versions prior to 1.4

How can you consider this "not a bug"?

Not only is the documentation contradictory in 1.4.0_01, the 
1.4 behavior represents a significant spec change from 
previous versions. getTime() used to return only integral 
seconds; now it returns milliseconds. The documented advice 
on adding fractional seconds to the results of getTime() is no 
longer valid in 1.4. 

It's hard to believe you have gone to great lengths to 
reduce user confusion when the api at 
http://java.sun.com/j2se/1.4/docs/api states "If a time value 
that includes the fractional seconds is desired, you must 
convert nanos to milliseconds (nanos/1000000) and add 
this to the getTime value".

More important, this is a really significant change from 1.3 
that I don't see a compelling reason for.  If our unit tests 
hadn't caught this it would have caused serious problems 
in our application.  As it is we are forced to code for either 
1.3 or 1.4.

I did some more searching.  Anyone interested in this bug 
should look at Bug# 4717216.  It says the documentation 
has been changed in a future (I assume unreleased) 
version.  The behavior is going to remain incompatible with 
jdk1.3 and before.

I wholeheartedly agree with the other people commenting on 
this bug.  The documentation in the says it returns only 
integral seconds.  However this is not correct, it includes 
fractional seconds to millisecond precision.  Either the 
behavior is wrong or the documentation is wrong.  Also this 
method is not forward compatible from 1.3.  That should be 
documented.  Any program from 1.3 or before that relied on 
the time being exact to any fractional precision from 
java.sql.Timestamp.getTime() or getNanos() will NOT work in 
1.4.  I checked version 1.4.1 and the part of the 
documentation that tells you to divide the nanoseconds by 
1000000 is still present.  If users do this, then their time 
values will be wrong!

This clearly is a bug in 1.4.  Changing the documentation to 
reflect the new behavior doesn't "fix it" at all.  It just 
confirms that the new behavior is going to be considered 
correct even though Timestamp has not behaved this way in 
JDK 1.2 or 1.3.

In many ways, the new behavior is better and lets Timestamp 
be a proper subclass of Date, but as the JDK went out of its 
way to tell us that it should work the previously ignorant 
way, this should stay.  Changing the behavior of a method 
this much is taboo in code and should have required some 
sort of deprecation of the previous calls to be replaced by a 
new call that behaved in the new way.

Of course, it never returned time in seconds, it's just that the 
milliseconds were zeroed out.  That is 1000 means 1 second.

It's also BROKEN that the new API actually now OVERRIDES 
the getTime() method of Date, yet it now behaves just like 
Date and should not override it.  Anyway, it's a mess and 
essentially breaks all code that deals with Timestamps such 
that not only are the Timestamp values wrong, but for any 
Timestamp in which the milliseconds value is 500-999 will now 
also result in a bump in the seconds field of that Timestamp 
(because we add the nanos value in).

The only solution now is for your code to do alternative 
behavior between 1.3 and 1.4, or force ALL code to revert to 
the 1.3 look by taking (getTime() / 1000) * 1000 to zero out 
those milliseconds so the adding of the nanos works.  This is 
ugly because it has NO EFFECT on 3.1 code other than 
creating more computation, and for 1.4, it's worthless since 
the division/multiplication and the nanos retrieval and division 
are not necessary anymore.

Most people like myself are worried about changing our code 
since we have to make it work under both JDKs, and it's not 
clear which way will remain as the "true" version.

Your API developers are way off on this one as a major 
change in the values returned should NEVER impact a method 
without deprecating the old and creating a new one.  It's 
called "design by contract" and this is clearly not holding up.

This 'BUG' broke our code and we basically have to scrap 
going to JDK 1.4 because of it. Our schedule doesn't permit 
us to change all of our code and then regression test every 
single item that deals with timestamps.

The original behavior should have stayed and been 
deprecated and a new method should have been added. 
Making developers finding these API changes through testing 
is not the correct way to release your code. Sun should have 
released a document stating what will break if you upgrade to 
1.4. We were already bitten by the little-documented focus 
event handler change.