argius note

プログラミング関連

java.sql.Timestampクラスの説明がおかしい?

今まで別の問題だと勘違いして放置していたんですが.....

まず、Java開発者向けドキュメントの"JDBC入門"の「SQL と Java の型のマッピング」という章で、以下のようなサンプルコードが書かれています。(最後の行だけ私が追加しました。)

Timestamp t = new Timestamp(98724573287540L);
java.util.Date d;
d = new java.util.Date(t.getTime() + (t.getNanos() / 1000000));
System.out.println(d.getTime());

そして、Javadoc(5.0日本語版)のTimestampのクラスの説明を引用します。

注: この型は java.util.Date と各ナノ秒値からなります。秒の整数値だけが java.util.Date の構成要素内に格納され、小数点以下の秒 (秒の nanos 値) は別の構成要素内に格納されます。getTime メソッドは、秒の整数値だけを返します。小数点以下の秒を含む時間値が必要な場合は、秒の nanos 値をミリ秒 (1000000 分の nanos) に変換し getTime 値に加える必要があります。

これらの記述によれば、サンプルコードの出力値は"98724573287540L"になると思うんですが、なりません。「getTime メソッドは、秒の整数値だけを返します。」と書かれているにも関わらず、実際はミリ秒単位もそのまま返されてしまいます。Java1.4,1.5,1.6で試しましたが、結果は同じでした。実装が「正」だとすれば、ドキュメントがことごとく間違っている、ということになるのでしょうか。だれもナノ秒なんて使わないから困らなかったんでしょうか。

今回明らかになったのは、外部から提供されたライブラリの実装が、上記のサンプルのようになっていたため、正確なタイムスタンプ値が取得できない問題があったからでした。テストしていないんでしょうか...

追記:コトの顛末

Java1.4.1のJavaAPI仕様までは、"The getTime method will return only integral seconds."が残ってますね。1.4.2以降では削除されています。でも、未だに中途半端な気がします。ここまでやるんだったら、「ミリ秒までは、java.util.Dateと同じ」にしてしまえば良かったんじゃないんですか?