001 /*
002 * Copyright 1996-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.sql;
027
028 import java.util.StringTokenizer;
029
030 /**
031 * <P>A thin wrapper around <code>java.util.Date</code> that allows
032 * the JDBC API to identify this as an SQL <code>TIMESTAMP</code> value.
033 * It adds the ability
034 * to hold the SQL <code>TIMESTAMP</code> fractional seconds value, by allowing
035 * the specification of fractional seconds to a precision of nanoseconds.
036 * A Timestamp also provides formatting and
037 * parsing operations to support the JDBC escape syntax for timestamp values.
038 *
039 * <p>The precision of a Timestamp object is calculated to be either:
040 * <ul>
041 * <li><code>19 </code>, which is the number of characters in yyyy-mm-dd hh:mm:ss
042 * <li> <code> 20 + s </code>, which is the number
043 * of characters in the yyyy-mm-dd hh:mm:ss.[fff...] and <code>s</code> represents the scale of the given Timestamp,
044 * its fractional seconds precision.
045 *</ul>
046 *
047 * <P><B>Note:</B> This type is a composite of a <code>java.util.Date</code> and a
048 * separate nanoseconds value. Only integral seconds are stored in the
049 * <code>java.util.Date</code> component. The fractional seconds - the nanos - are
050 * separate. The <code>Timestamp.equals(Object)</code> method never returns
051 * <code>true</code> when passed an object
052 * that isn't an instance of <code>java.sql.Timestamp</code>,
053 * because the nanos component of a date is unknown.
054 * As a result, the <code>Timestamp.equals(Object)</code>
055 * method is not symmetric with respect to the
056 * <code>java.util.Date.equals(Object)</code>
057 * method. Also, the <code>hashcode</code> method uses the underlying
058 * <code>java.util.Date</code>
059 * implementation and therefore does not include nanos in its computation.
060 * <P>
061 * Due to the differences between the <code>Timestamp</code> class
062 * and the <code>java.util.Date</code>
063 * class mentioned above, it is recommended that code not view
064 * <code>Timestamp</code> values generically as an instance of
065 * <code>java.util.Date</code>. The
066 * inheritance relationship between <code>Timestamp</code>
067 * and <code>java.util.Date</code> really
068 * denotes implementation inheritance, and not type inheritance.
069 */
070 public class Timestamp extends java.util.Date {
071
072 /**
073 * Constructs a <code>Timestamp</code> object initialized
074 * with the given values.
075 *
076 * @param year the year minus 1900
077 * @param month 0 to 11
078 * @param date 1 to 31
079 * @param hour 0 to 23
080 * @param minute 0 to 59
081 * @param second 0 to 59
082 * @param nano 0 to 999,999,999
083 * @deprecated instead use the constructor <code>Timestamp(long millis)</code>
084 * @exception IllegalArgumentException if the nano argument is out of bounds
085 */
086 @Deprecated
087 public Timestamp(int year, int month, int date, int hour,
088 int minute, int second, int nano) {
089 super (year, month, date, hour, minute, second);
090 if (nano > 999999999 || nano < 0) {
091 throw new IllegalArgumentException(
092 "nanos > 999999999 or < 0");
093 }
094 nanos = nano;
095 }
096
097 /**
098 * Constructs a <code>Timestamp</code> object
099 * using a milliseconds time value. The
100 * integral seconds are stored in the underlying date value; the
101 * fractional seconds are stored in the <code>nanos</code> field of
102 * the <code>Timestamp</code> object.
103 *
104 * @param time milliseconds since January 1, 1970, 00:00:00 GMT.
105 * A negative number is the number of milliseconds before
106 * January 1, 1970, 00:00:00 GMT.
107 * @see java.util.Calendar
108 */
109 public Timestamp(long time) {
110 super ((time / 1000) * 1000);
111 nanos = (int) ((time % 1000) * 1000000);
112 if (nanos < 0) {
113 nanos = 1000000000 + nanos;
114 super .setTime(((time / 1000) - 1) * 1000);
115 }
116 }
117
118 /**
119 * Sets this <code>Timestamp</code> object to represent a point in time that is
120 * <tt>time</tt> milliseconds after January 1, 1970 00:00:00 GMT.
121 *
122 * @param time the number of milliseconds.
123 * @see #getTime
124 * @see #Timestamp(long time)
125 * @see java.util.Calendar
126 */
127 public void setTime(long time) {
128 super .setTime((time / 1000) * 1000);
129 nanos = (int) ((time % 1000) * 1000000);
130 if (nanos < 0) {
131 nanos = 1000000000 + nanos;
132 super .setTime(((time / 1000) - 1) * 1000);
133 }
134 }
135
136 /**
137 * Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT
138 * represented by this <code>Timestamp</code> object.
139 *
140 * @return the number of milliseconds since January 1, 1970, 00:00:00 GMT
141 * represented by this date.
142 * @see #setTime
143 */
144 public long getTime() {
145 long time = super .getTime();
146 return (time + (nanos / 1000000));
147 }
148
149 /**
150 * @serial
151 */
152 private int nanos;
153
154 /**
155 * Converts a <code>String</code> object in JDBC timestamp escape format to a
156 * <code>Timestamp</code> value.
157 *
158 * @param s timestamp in format <code>yyyy-mm-dd hh:mm:ss[.f...]</code>. The
159 * fractional seconds may be omitted.
160 * @return corresponding <code>Timestamp</code> value
161 * @exception java.lang.IllegalArgumentException if the given argument
162 * does not have the format <code>yyyy-mm-dd hh:mm:ss[.f...]</code>
163 */
164 public static Timestamp valueOf(String s) {
165 String date_s;
166 String time_s;
167 String nanos_s;
168 int year;
169 int month;
170 int day;
171 int hour;
172 int minute;
173 int second;
174 int a_nanos = 0;
175 int firstDash;
176 int secondDash;
177 int dividingSpace;
178 int firstColon = 0;
179 int secondColon = 0;
180 int period = 0;
181 String formatError = "Timestamp format must be yyyy-mm-dd hh:mm:ss[.fffffffff]";
182 String zeros = "000000000";
183 String delimiterDate = "-";
184 String delimiterTime = ":";
185 StringTokenizer stringTokeninzerDate;
186 StringTokenizer stringTokeninzerTime;
187
188 if (s == null)
189 throw new java.lang.IllegalArgumentException("null string");
190
191 int counterD = 0;
192 int intDate[] = { 4, 2, 2 };
193
194 int counterT = 0;
195 int intTime[] = { 2, 2, 12 };
196
197 // Split the string into date and time components
198 s = s.trim();
199 dividingSpace = s.indexOf(' ');
200 if (dividingSpace > 0) {
201 date_s = s.substring(0, dividingSpace);
202 time_s = s.substring(dividingSpace + 1);
203 } else {
204 throw new java.lang.IllegalArgumentException(formatError);
205 }
206
207 stringTokeninzerTime = new StringTokenizer(time_s,
208 delimiterTime);
209 stringTokeninzerDate = new StringTokenizer(date_s,
210 delimiterDate);
211
212 while (stringTokeninzerDate.hasMoreTokens()) {
213 String tokenDate = stringTokeninzerDate.nextToken();
214 if (tokenDate.length() != intDate[counterD]) {
215 throw new java.lang.IllegalArgumentException(
216 formatError);
217 }
218 counterD++;
219 }
220
221 /*
222 //Commenting this portion out for checking of time
223
224 while(stringTokeninzerTime.hasMoreTokens()) {
225 String tokenTime = stringTokeninzerTime.nextToken();
226
227 if (counterT < 2 && tokenTime.length() != intTime[counterT] ) {
228 throw new java.lang.IllegalArgumentException(formatError);
229 }
230 counterT++;
231 }
232 */
233
234 // Parse the date
235 firstDash = date_s.indexOf('-');
236 secondDash = date_s.indexOf('-', firstDash + 1);
237
238 // Parse the time
239 if (time_s == null)
240 throw new java.lang.IllegalArgumentException(formatError);
241 firstColon = time_s.indexOf(':');
242 secondColon = time_s.indexOf(':', firstColon + 1);
243 period = time_s.indexOf('.', secondColon + 1);
244
245 // Convert the date
246 if ((firstDash > 0) && (secondDash > 0)
247 && (secondDash < date_s.length() - 1)) {
248 year = Integer.parseInt(date_s.substring(0, firstDash)) - 1900;
249 month = Integer.parseInt(date_s.substring(firstDash + 1,
250 secondDash)) - 1;
251 day = Integer.parseInt(date_s.substring(secondDash + 1));
252 } else {
253 throw new java.lang.IllegalArgumentException(formatError);
254 }
255
256 // Convert the time; default missing nanos
257 if ((firstColon > 0) & (secondColon > 0)
258 & (secondColon < time_s.length() - 1)) {
259 hour = Integer.parseInt(time_s.substring(0, firstColon));
260 minute = Integer.parseInt(time_s.substring(firstColon + 1,
261 secondColon));
262 if ((period > 0) & (period < time_s.length() - 1)) {
263 second = Integer.parseInt(time_s.substring(
264 secondColon + 1, period));
265 nanos_s = time_s.substring(period + 1);
266 if (nanos_s.length() > 9)
267 throw new java.lang.IllegalArgumentException(
268 formatError);
269 if (!Character.isDigit(nanos_s.charAt(0)))
270 throw new java.lang.IllegalArgumentException(
271 formatError);
272 nanos_s = nanos_s
273 + zeros.substring(0, 9 - nanos_s.length());
274 a_nanos = Integer.parseInt(nanos_s);
275 } else if (period > 0) {
276 throw new java.lang.IllegalArgumentException(
277 formatError);
278 } else {
279 second = Integer.parseInt(time_s
280 .substring(secondColon + 1));
281 }
282 } else {
283 throw new java.lang.IllegalArgumentException();
284 }
285
286 return new Timestamp(year, month, day, hour, minute, second,
287 a_nanos);
288 }
289
290 /**
291 * Formats a timestamp in JDBC timestamp escape format.
292 * <code>yyyy-mm-dd hh:mm:ss.fffffffff</code>,
293 * where <code>ffffffffff</code> indicates nanoseconds.
294 * <P>
295 * @return a <code>String</code> object in
296 * <code>yyyy-mm-dd hh:mm:ss.fffffffff</code> format
297 */
298 public String toString() {
299
300 int year = super .getYear() + 1900;
301 int month = super .getMonth() + 1;
302 int day = super .getDate();
303 int hour = super .getHours();
304 int minute = super .getMinutes();
305 int second = super .getSeconds();
306 String yearString;
307 String monthString;
308 String dayString;
309 String hourString;
310 String minuteString;
311 String secondString;
312 String nanosString;
313 String zeros = "000000000";
314 String yearZeros = "0000";
315 StringBuffer timestampBuf;
316
317 if (year < 1000) {
318 // Add leading zeros
319 yearString = "" + year;
320 yearString = yearZeros.substring(0, (4 - yearString
321 .length()))
322 + yearString;
323 } else {
324 yearString = "" + year;
325 }
326 if (month < 10) {
327 monthString = "0" + month;
328 } else {
329 monthString = Integer.toString(month);
330 }
331 if (day < 10) {
332 dayString = "0" + day;
333 } else {
334 dayString = Integer.toString(day);
335 }
336 if (hour < 10) {
337 hourString = "0" + hour;
338 } else {
339 hourString = Integer.toString(hour);
340 }
341 if (minute < 10) {
342 minuteString = "0" + minute;
343 } else {
344 minuteString = Integer.toString(minute);
345 }
346 if (second < 10) {
347 secondString = "0" + second;
348 } else {
349 secondString = Integer.toString(second);
350 }
351 if (nanos == 0) {
352 nanosString = "0";
353 } else {
354 nanosString = Integer.toString(nanos);
355
356 // Add leading zeros
357 nanosString = zeros
358 .substring(0, (9 - nanosString.length()))
359 + nanosString;
360
361 // Truncate trailing zeros
362 char[] nanosChar = new char[nanosString.length()];
363 nanosString.getChars(0, nanosString.length(), nanosChar, 0);
364 int truncIndex = 8;
365 while (nanosChar[truncIndex] == '0') {
366 truncIndex--;
367 }
368
369 nanosString = new String(nanosChar, 0, truncIndex + 1);
370 }
371
372 // do a string buffer here instead.
373 timestampBuf = new StringBuffer(20 + nanosString.length());
374 timestampBuf.append(yearString);
375 timestampBuf.append("-");
376 timestampBuf.append(monthString);
377 timestampBuf.append("-");
378 timestampBuf.append(dayString);
379 timestampBuf.append(" ");
380 timestampBuf.append(hourString);
381 timestampBuf.append(":");
382 timestampBuf.append(minuteString);
383 timestampBuf.append(":");
384 timestampBuf.append(secondString);
385 timestampBuf.append(".");
386 timestampBuf.append(nanosString);
387
388 return (timestampBuf.toString());
389 }
390
391 /**
392 * Gets this <code>Timestamp</code> object's <code>nanos</code> value.
393 *
394 * @return this <code>Timestamp</code> object's fractional seconds component
395 * @see #setNanos
396 */
397 public int getNanos() {
398 return nanos;
399 }
400
401 /**
402 * Sets this <code>Timestamp</code> object's <code>nanos</code> field
403 * to the given value.
404 *
405 * @param n the new fractional seconds component
406 * @exception java.lang.IllegalArgumentException if the given argument
407 * is greater than 999999999 or less than 0
408 * @see #getNanos
409 */
410 public void setNanos(int n) {
411 if (n > 999999999 || n < 0) {
412 throw new IllegalArgumentException(
413 "nanos > 999999999 or < 0");
414 }
415 nanos = n;
416 }
417
418 /**
419 * Tests to see if this <code>Timestamp</code> object is
420 * equal to the given <code>Timestamp</code> object.
421 *
422 * @param ts the <code>Timestamp</code> value to compare with
423 * @return <code>true</code> if the given <code>Timestamp</code>
424 * object is equal to this <code>Timestamp</code> object;
425 * <code>false</code> otherwise
426 */
427 public boolean equals(Timestamp ts) {
428 if (super .equals(ts)) {
429 if (nanos == ts.nanos) {
430 return true;
431 } else {
432 return false;
433 }
434 } else {
435 return false;
436 }
437 }
438
439 /**
440 * Tests to see if this <code>Timestamp</code> object is
441 * equal to the given object.
442 *
443 * This version of the method <code>equals</code> has been added
444 * to fix the incorrect
445 * signature of <code>Timestamp.equals(Timestamp)</code> and to preserve backward
446 * compatibility with existing class files.
447 *
448 * Note: This method is not symmetric with respect to the
449 * <code>equals(Object)</code> method in the base class.
450 *
451 * @param ts the <code>Object</code> value to compare with
452 * @return <code>true</code> if the given <code>Object</code> is an instance
453 * of a <code>Timestamp</code> that
454 * is equal to this <code>Timestamp</code> object;
455 * <code>false</code> otherwise
456 */
457 public boolean equals(java.lang.Object ts) {
458 if (ts instanceof Timestamp) {
459 return this .equals((Timestamp) ts);
460 } else {
461 return false;
462 }
463 }
464
465 /**
466 * Indicates whether this <code>Timestamp</code> object is
467 * earlier than the given <code>Timestamp</code> object.
468 *
469 * @param ts the <code>Timestamp</code> value to compare with
470 * @return <code>true</code> if this <code>Timestamp</code> object is earlier;
471 * <code>false</code> otherwise
472 */
473 public boolean before(Timestamp ts) {
474 return compareTo(ts) < 0;
475 }
476
477 /**
478 * Indicates whether this <code>Timestamp</code> object is
479 * later than the given <code>Timestamp</code> object.
480 *
481 * @param ts the <code>Timestamp</code> value to compare with
482 * @return <code>true</code> if this <code>Timestamp</code> object is later;
483 * <code>false</code> otherwise
484 */
485 public boolean after(Timestamp ts) {
486 return compareTo(ts) > 0;
487 }
488
489 /**
490 * Compares this <code>Timestamp</code> object to the given
491 * <code>Timestamp</code> object.
492 *
493 * @param ts the <code>Timestamp</code> object to be compared to
494 * this <code>Timestamp</code> object
495 * @return the value <code>0</code> if the two <code>Timestamp</code>
496 * objects are equal; a value less than <code>0</code> if this
497 * <code>Timestamp</code> object is before the given argument;
498 * and a value greater than <code>0</code> if this
499 * <code>Timestamp</code> object is after the given argument.
500 * @since 1.4
501 */
502 public int compareTo(Timestamp ts) {
503 int i = super .compareTo(ts);
504 if (i == 0) {
505 if (nanos > ts.nanos) {
506 return 1;
507 } else if (nanos < ts.nanos) {
508 return -1;
509 }
510 }
511 return i;
512
513 }
514
515 /**
516 * Compares this <code>Timestamp</code> object to the given
517 * <code>Date</code>, which must be a <code>Timestamp</code>
518 * object. If the argument is not a <code>Timestamp</code> object,
519 * this method throws a <code>ClassCastException</code> object.
520 * (<code>Timestamp</code> objects are
521 * comparable only to other <code>Timestamp</code> objects.)
522 *
523 * @param o the <code>Date</code> to be compared, which must be a
524 * <code>Timestamp</code> object
525 * @return the value <code>0</code> if this <code>Timestamp</code> object
526 * and the given object are equal; a value less than <code>0</code>
527 * if this <code>Timestamp</code> object is before the given argument;
528 * and a value greater than <code>0</code> if this
529 * <code>Timestamp</code> object is after the given argument.
530 *
531 * @since 1.5
532 */
533 public int compareTo(java.util.Date o) {
534 if (o instanceof Timestamp) {
535 // When Timestamp instance compare it with a Timestamp
536 // Hence it is basically calling this.compareTo((Timestamp))o);
537 // Note typecasting is safe because o is instance of Timestamp
538 return compareTo((Timestamp) o);
539 } else {
540 // When Date doing a o.compareTo(this)
541 // will give wrong results.
542 Timestamp ts = new Timestamp(o.getTime());
543 return this .compareTo(ts);
544 }
545 }
546
547 static final long serialVersionUID = 2745179027874758501L;
548
549 }
|