View Javadoc
1   /*
2    * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package java.sql;
27  
28  import java.time.Instant;
29  import java.time.LocalDateTime;
30  import java.util.StringTokenizer;
31  
32  /**
33   * <P>A thin wrapper around <code>java.util.Date</code> that allows
34   * the JDBC API to identify this as an SQL <code>TIMESTAMP</code> value.
35   * It adds the ability
36   * to hold the SQL <code>TIMESTAMP</code> fractional seconds value, by allowing
37   * the specification of fractional seconds to a precision of nanoseconds.
38   * A Timestamp also provides formatting and
39   * parsing operations to support the JDBC escape syntax for timestamp values.
40   *
41   * <p>The precision of a Timestamp object is calculated to be either:
42   * <ul>
43   * <li><code>19 </code>, which is the number of characters in yyyy-mm-dd hh:mm:ss
44   * <li> <code> 20 + s </code>, which is the number
45   * of characters in the yyyy-mm-dd hh:mm:ss.[fff...] and <code>s</code> represents  the scale of the given Timestamp,
46   * its fractional seconds precision.
47   *</ul>
48   *
49   * <P><B>Note:</B> This type is a composite of a <code>java.util.Date</code> and a
50   * separate nanoseconds value. Only integral seconds are stored in the
51   * <code>java.util.Date</code> component. The fractional seconds - the nanos - are
52   * separate.  The <code>Timestamp.equals(Object)</code> method never returns
53   * <code>true</code> when passed an object
54   * that isn't an instance of <code>java.sql.Timestamp</code>,
55   * because the nanos component of a date is unknown.
56   * As a result, the <code>Timestamp.equals(Object)</code>
57   * method is not symmetric with respect to the
58   * <code>java.util.Date.equals(Object)</code>
59   * method.  Also, the <code>hashCode</code> method uses the underlying
60   * <code>java.util.Date</code>
61   * implementation and therefore does not include nanos in its computation.
62   * <P>
63   * Due to the differences between the <code>Timestamp</code> class
64   * and the <code>java.util.Date</code>
65   * class mentioned above, it is recommended that code not view
66   * <code>Timestamp</code> values generically as an instance of
67   * <code>java.util.Date</code>.  The
68   * inheritance relationship between <code>Timestamp</code>
69   * and <code>java.util.Date</code> really
70   * denotes implementation inheritance, and not type inheritance.
71   */
72  public class Timestamp extends java.util.Date {
73  
74      /**
75       * Constructs a <code>Timestamp</code> object initialized
76       * with the given values.
77       *
78       * @param year the year minus 1900
79       * @param month 0 to 11
80       * @param date 1 to 31
81       * @param hour 0 to 23
82       * @param minute 0 to 59
83       * @param second 0 to 59
84       * @param nano 0 to 999,999,999
85       * @deprecated instead use the constructor <code>Timestamp(long millis)</code>
86       * @exception IllegalArgumentException if the nano argument is out of bounds
87       */
88      @Deprecated
89      public Timestamp(int year, int month, int date,
90                       int hour, int minute, int second, int nano) {
91          super(year, month, date, hour, minute, second);
92          if (nano > 999999999 || nano < 0) {
93              throw new IllegalArgumentException("nanos > 999999999 or < 0");
94          }
95          nanos = nano;
96      }
97  
98      /**
99       * Constructs a <code>Timestamp</code> object
100      * using a milliseconds time value. The
101      * integral seconds are stored in the underlying date value; the
102      * fractional seconds are stored in the <code>nanos</code> field of
103      * the <code>Timestamp</code> object.
104      *
105      * @param time milliseconds since January 1, 1970, 00:00:00 GMT.
106      *        A negative number is the number of milliseconds before
107      *         January 1, 1970, 00:00:00 GMT.
108      * @see java.util.Calendar
109      */
110     public Timestamp(long time) {
111         super((time/1000)*1000);
112         nanos = (int)((time%1000) * 1000000);
113         if (nanos < 0) {
114             nanos = 1000000000 + nanos;
115             super.setTime(((time/1000)-1)*1000);
116         }
117     }
118 
119     /**
120      * Sets this <code>Timestamp</code> object to represent a point in time that is
121      * <tt>time</tt> milliseconds after January 1, 1970 00:00:00 GMT.
122      *
123      * @param time   the number of milliseconds.
124      * @see #getTime
125      * @see #Timestamp(long time)
126      * @see java.util.Calendar
127      */
128     public void setTime(long time) {
129         super.setTime((time/1000)*1000);
130         nanos = (int)((time%1000) * 1000000);
131         if (nanos < 0) {
132             nanos = 1000000000 + nanos;
133             super.setTime(((time/1000)-1)*1000);
134         }
135     }
136 
137     /**
138      * Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT
139      * represented by this <code>Timestamp</code> object.
140      *
141      * @return  the number of milliseconds since January 1, 1970, 00:00:00 GMT
142      *          represented by this date.
143      * @see #setTime
144      */
145     public long getTime() {
146         long time = super.getTime();
147         return (time + (nanos / 1000000));
148     }
149 
150 
151     /**
152      * @serial
153      */
154     private int nanos;
155 
156     /**
157      * Converts a <code>String</code> object in JDBC timestamp escape format to a
158      * <code>Timestamp</code> value.
159      *
160      * @param s timestamp in format <code>yyyy-[m]m-[d]d hh:mm:ss[.f...]</code>.  The
161      * fractional seconds may be omitted. The leading zero for <code>mm</code>
162      * and <code>dd</code> may also be omitted.
163      *
164      * @return corresponding <code>Timestamp</code> value
165      * @exception java.lang.IllegalArgumentException if the given argument
166      * does not have the format <code>yyyy-[m]m-[d]d hh:mm:ss[.f...]</code>
167      */
168     public static Timestamp valueOf(String s) {
169         final int YEAR_LENGTH = 4;
170         final int MONTH_LENGTH = 2;
171         final int DAY_LENGTH = 2;
172         final int MAX_MONTH = 12;
173         final int MAX_DAY = 31;
174         String date_s;
175         String time_s;
176         String nanos_s;
177         int year = 0;
178         int month = 0;
179         int day = 0;
180         int hour;
181         int minute;
182         int second;
183         int a_nanos = 0;
184         int firstDash;
185         int secondDash;
186         int dividingSpace;
187         int firstColon = 0;
188         int secondColon = 0;
189         int period = 0;
190         String formatError = "Timestamp format must be yyyy-mm-dd hh:mm:ss[.fffffffff]";
191         String zeros = "000000000";
192         String delimiterDate = "-";
193         String delimiterTime = ":";
194 
195         if (s == null) throw new java.lang.IllegalArgumentException("null string");
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         // Parse the date
208         firstDash = date_s.indexOf('-');
209         secondDash = date_s.indexOf('-', firstDash+1);
210 
211         // Parse the time
212         if (time_s == null)
213             throw new java.lang.IllegalArgumentException(formatError);
214         firstColon = time_s.indexOf(':');
215         secondColon = time_s.indexOf(':', firstColon+1);
216         period = time_s.indexOf('.', secondColon+1);
217 
218         // Convert the date
219         boolean parsedDate = false;
220         if ((firstDash > 0) && (secondDash > 0) && (secondDash < date_s.length() - 1)) {
221             String yyyy = date_s.substring(0, firstDash);
222             String mm = date_s.substring(firstDash + 1, secondDash);
223             String dd = date_s.substring(secondDash + 1);
224             if (yyyy.length() == YEAR_LENGTH &&
225                     (mm.length() >= 1 && mm.length() <= MONTH_LENGTH) &&
226                     (dd.length() >= 1 && dd.length() <= DAY_LENGTH)) {
227                  year = Integer.parseInt(yyyy);
228                  month = Integer.parseInt(mm);
229                  day = Integer.parseInt(dd);
230 
231                 if ((month >= 1 && month <= MAX_MONTH) && (day >= 1 && day <= MAX_DAY)) {
232                     parsedDate = true;
233                 }
234             }
235         }
236         if (! parsedDate) {
237             throw new java.lang.IllegalArgumentException(formatError);
238         }
239 
240         // Convert the time; default missing nanos
241         if ((firstColon > 0) & (secondColon > 0) &
242             (secondColon < time_s.length()-1)) {
243             hour = Integer.parseInt(time_s.substring(0, firstColon));
244             minute =
245                 Integer.parseInt(time_s.substring(firstColon+1, secondColon));
246             if ((period > 0) & (period < time_s.length()-1)) {
247                 second =
248                     Integer.parseInt(time_s.substring(secondColon+1, period));
249                 nanos_s = time_s.substring(period+1);
250                 if (nanos_s.length() > 9)
251                     throw new java.lang.IllegalArgumentException(formatError);
252                 if (!Character.isDigit(nanos_s.charAt(0)))
253                     throw new java.lang.IllegalArgumentException(formatError);
254                 nanos_s = nanos_s + zeros.substring(0,9-nanos_s.length());
255                 a_nanos = Integer.parseInt(nanos_s);
256             } else if (period > 0) {
257                 throw new java.lang.IllegalArgumentException(formatError);
258             } else {
259                 second = Integer.parseInt(time_s.substring(secondColon+1));
260             }
261         } else {
262             throw new java.lang.IllegalArgumentException(formatError);
263         }
264 
265         return new Timestamp(year - 1900, month - 1, day, hour, minute, second, a_nanos);
266     }
267 
268     /**
269      * Formats a timestamp in JDBC timestamp escape format.
270      *         <code>yyyy-mm-dd hh:mm:ss.fffffffff</code>,
271      * where <code>ffffffffff</code> indicates nanoseconds.
272      * <P>
273      * @return a <code>String</code> object in
274      *           <code>yyyy-mm-dd hh:mm:ss.fffffffff</code> format
275      */
276     @SuppressWarnings("deprecation")
277     public String toString () {
278 
279         int year = super.getYear() + 1900;
280         int month = super.getMonth() + 1;
281         int day = super.getDate();
282         int hour = super.getHours();
283         int minute = super.getMinutes();
284         int second = super.getSeconds();
285         String yearString;
286         String monthString;
287         String dayString;
288         String hourString;
289         String minuteString;
290         String secondString;
291         String nanosString;
292         String zeros = "000000000";
293         String yearZeros = "0000";
294         StringBuffer timestampBuf;
295 
296         if (year < 1000) {
297             // Add leading zeros
298             yearString = "" + year;
299             yearString = yearZeros.substring(0, (4-yearString.length())) +
300                 yearString;
301         } else {
302             yearString = "" + year;
303         }
304         if (month < 10) {
305             monthString = "0" + month;
306         } else {
307             monthString = Integer.toString(month);
308         }
309         if (day < 10) {
310             dayString = "0" + day;
311         } else {
312             dayString = Integer.toString(day);
313         }
314         if (hour < 10) {
315             hourString = "0" + hour;
316         } else {
317             hourString = Integer.toString(hour);
318         }
319         if (minute < 10) {
320             minuteString = "0" + minute;
321         } else {
322             minuteString = Integer.toString(minute);
323         }
324         if (second < 10) {
325             secondString = "0" + second;
326         } else {
327             secondString = Integer.toString(second);
328         }
329         if (nanos == 0) {
330             nanosString = "0";
331         } else {
332             nanosString = Integer.toString(nanos);
333 
334             // Add leading zeros
335             nanosString = zeros.substring(0, (9-nanosString.length())) +
336                 nanosString;
337 
338             // Truncate trailing zeros
339             char[] nanosChar = new char[nanosString.length()];
340             nanosString.getChars(0, nanosString.length(), nanosChar, 0);
341             int truncIndex = 8;
342             while (nanosChar[truncIndex] == '0') {
343                 truncIndex--;
344             }
345 
346             nanosString = new String(nanosChar, 0, truncIndex + 1);
347         }
348 
349         // do a string buffer here instead.
350         timestampBuf = new StringBuffer(20+nanosString.length());
351         timestampBuf.append(yearString);
352         timestampBuf.append("-");
353         timestampBuf.append(monthString);
354         timestampBuf.append("-");
355         timestampBuf.append(dayString);
356         timestampBuf.append(" ");
357         timestampBuf.append(hourString);
358         timestampBuf.append(":");
359         timestampBuf.append(minuteString);
360         timestampBuf.append(":");
361         timestampBuf.append(secondString);
362         timestampBuf.append(".");
363         timestampBuf.append(nanosString);
364 
365         return (timestampBuf.toString());
366     }
367 
368     /**
369      * Gets this <code>Timestamp</code> object's <code>nanos</code> value.
370      *
371      * @return this <code>Timestamp</code> object's fractional seconds component
372      * @see #setNanos
373      */
374     public int getNanos() {
375         return nanos;
376     }
377 
378     /**
379      * Sets this <code>Timestamp</code> object's <code>nanos</code> field
380      * to the given value.
381      *
382      * @param n the new fractional seconds component
383      * @exception java.lang.IllegalArgumentException if the given argument
384      *            is greater than 999999999 or less than 0
385      * @see #getNanos
386      */
387     public void setNanos(int n) {
388         if (n > 999999999 || n < 0) {
389             throw new IllegalArgumentException("nanos > 999999999 or < 0");
390         }
391         nanos = n;
392     }
393 
394     /**
395      * Tests to see if this <code>Timestamp</code> object is
396      * equal to the given <code>Timestamp</code> object.
397      *
398      * @param ts the <code>Timestamp</code> value to compare with
399      * @return <code>true</code> if the given <code>Timestamp</code>
400      *         object is equal to this <code>Timestamp</code> object;
401      *         <code>false</code> otherwise
402      */
403     public boolean equals(Timestamp ts) {
404         if (super.equals(ts)) {
405             if  (nanos == ts.nanos) {
406                 return true;
407             } else {
408                 return false;
409             }
410         } else {
411             return false;
412         }
413     }
414 
415     /**
416      * Tests to see if this <code>Timestamp</code> object is
417      * equal to the given object.
418      *
419      * This version of the method <code>equals</code> has been added
420      * to fix the incorrect
421      * signature of <code>Timestamp.equals(Timestamp)</code> and to preserve backward
422      * compatibility with existing class files.
423      *
424      * Note: This method is not symmetric with respect to the
425      * <code>equals(Object)</code> method in the base class.
426      *
427      * @param ts the <code>Object</code> value to compare with
428      * @return <code>true</code> if the given <code>Object</code> is an instance
429      *         of a <code>Timestamp</code> that
430      *         is equal to this <code>Timestamp</code> object;
431      *         <code>false</code> otherwise
432      */
433     public boolean equals(java.lang.Object ts) {
434       if (ts instanceof Timestamp) {
435         return this.equals((Timestamp)ts);
436       } else {
437         return false;
438       }
439     }
440 
441     /**
442      * Indicates whether this <code>Timestamp</code> object is
443      * earlier than the given <code>Timestamp</code> object.
444      *
445      * @param ts the <code>Timestamp</code> value to compare with
446      * @return <code>true</code> if this <code>Timestamp</code> object is earlier;
447      *        <code>false</code> otherwise
448      */
449     public boolean before(Timestamp ts) {
450         return compareTo(ts) < 0;
451     }
452 
453     /**
454      * Indicates whether this <code>Timestamp</code> object is
455      * later than the given <code>Timestamp</code> object.
456      *
457      * @param ts the <code>Timestamp</code> value to compare with
458      * @return <code>true</code> if this <code>Timestamp</code> object is later;
459      *        <code>false</code> otherwise
460      */
461     public boolean after(Timestamp ts) {
462         return compareTo(ts) > 0;
463     }
464 
465     /**
466      * Compares this <code>Timestamp</code> object to the given
467      * <code>Timestamp</code> object.
468      *
469      * @param   ts   the <code>Timestamp</code> object to be compared to
470      *                this <code>Timestamp</code> object
471      * @return  the value <code>0</code> if the two <code>Timestamp</code>
472      *          objects are equal; a value less than <code>0</code> if this
473      *          <code>Timestamp</code> object is before the given argument;
474      *          and a value greater than <code>0</code> if this
475      *          <code>Timestamp</code> object is after the given argument.
476      * @since   1.4
477      */
478     public int compareTo(Timestamp ts) {
479         long thisTime = this.getTime();
480         long anotherTime = ts.getTime();
481         int i = (thisTime<anotherTime ? -1 :(thisTime==anotherTime?0 :1));
482         if (i == 0) {
483             if (nanos > ts.nanos) {
484                     return 1;
485             } else if (nanos < ts.nanos) {
486                 return -1;
487             }
488         }
489         return i;
490     }
491 
492     /**
493      * Compares this <code>Timestamp</code> object to the given
494      * <code>Date</code> object.
495      *
496      * @param o the <code>Date</code> to be compared to
497      *          this <code>Timestamp</code> object
498      * @return  the value <code>0</code> if this <code>Timestamp</code> object
499      *          and the given object are equal; a value less than <code>0</code>
500      *          if this  <code>Timestamp</code> object is before the given argument;
501      *          and a value greater than <code>0</code> if this
502      *          <code>Timestamp</code> object is after the given argument.
503      *
504      * @since   1.5
505      */
506     public int compareTo(java.util.Date o) {
507        if(o instanceof Timestamp) {
508             // When Timestamp instance compare it with a Timestamp
509             // Hence it is basically calling this.compareTo((Timestamp))o);
510             // Note typecasting is safe because o is instance of Timestamp
511            return compareTo((Timestamp)o);
512       } else {
513             // When Date doing a o.compareTo(this)
514             // will give wrong results.
515           Timestamp ts = new Timestamp(o.getTime());
516           return this.compareTo(ts);
517       }
518     }
519 
520     /**
521      * {@inheritDoc}
522      *
523      * The {@code hashCode} method uses the underlying {@code java.util.Date}
524      * implementation and therefore does not include nanos in its computation.
525      *
526      */
527     @Override
528     public int hashCode() {
529         return super.hashCode();
530     }
531 
532     static final long serialVersionUID = 2745179027874758501L;
533 
534     private static final int MILLIS_PER_SECOND = 1000;
535 
536     /**
537      * Obtains an instance of {@code Timestamp} from a {@code LocalDateTime}
538      * object, with the same year, month, day of month, hours, minutes,
539      * seconds and nanos date-time value as the provided {@code LocalDateTime}.
540      * <p>
541      * The provided {@code LocalDateTime} is interpreted as the local
542      * date-time in the local time zone.
543      *
544      * @param dateTime a {@code LocalDateTime} to convert
545      * @return a {@code Timestamp} object
546      * @exception NullPointerException if {@code dateTime} is null.
547      * @since 1.8
548      */
549     @SuppressWarnings("deprecation")
550     public static Timestamp valueOf(LocalDateTime dateTime) {
551         return new Timestamp(dateTime.getYear() - 1900,
552                              dateTime.getMonthValue() - 1,
553                              dateTime.getDayOfMonth(),
554                              dateTime.getHour(),
555                              dateTime.getMinute(),
556                              dateTime.getSecond(),
557                              dateTime.getNano());
558     }
559 
560     /**
561      * Converts this {@code Timestamp} object to a {@code LocalDateTime}.
562      * <p>
563      * The conversion creates a {@code LocalDateTime} that represents the
564      * same year, month, day of month, hours, minutes, seconds and nanos
565      * date-time value as this {@code Timestamp} in the local time zone.
566      *
567      * @return a {@code LocalDateTime} object representing the same date-time value
568      * @since 1.8
569      */
570     @SuppressWarnings("deprecation")
571     public LocalDateTime toLocalDateTime() {
572         return LocalDateTime.of(getYear() + 1900,
573                                 getMonth() + 1,
574                                 getDate(),
575                                 getHours(),
576                                 getMinutes(),
577                                 getSeconds(),
578                                 getNanos());
579     }
580 
581     /**
582      * Obtains an instance of {@code Timestamp} from an {@link Instant} object.
583      * <p>
584      * {@code Instant} can store points on the time-line further in the future
585      * and further in the past than {@code Date}. In this scenario, this method
586      * will throw an exception.
587      *
588      * @param instant  the instant to convert
589      * @return an {@code Timestamp} representing the same point on the time-line as
590      *  the provided instant
591      * @exception NullPointerException if {@code instant} is null.
592      * @exception IllegalArgumentException if the instant is too large to
593      *  represent as a {@code Timesamp}
594      * @since 1.8
595      */
596     public static Timestamp from(Instant instant) {
597         try {
598             Timestamp stamp = new Timestamp(instant.getEpochSecond() * MILLIS_PER_SECOND);
599             stamp.nanos = instant.getNano();
600             return stamp;
601         } catch (ArithmeticException ex) {
602             throw new IllegalArgumentException(ex);
603         }
604     }
605 
606     /**
607      * Converts this {@code Timestamp} object to an {@code Instant}.
608      * <p>
609      * The conversion creates an {@code Instant} that represents the same
610      * point on the time-line as this {@code Timestamp}.
611      *
612      * @return an instant representing the same point on the time-line
613      * @since 1.8
614      */
615     @Override
616     public Instant toInstant() {
617         return Instant.ofEpochSecond(super.getTime() / MILLIS_PER_SECOND, nanos);
618     }
619 }