Timestamp.java

/*
 * Copyright (c) 1996, 2025, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation. Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

packagejava.sql;

importjava.time.Instant;
importjava.time.LocalDateTime;

/**
 * <P>A thin wrapper around {@code java.util.Date} that allows
 * the JDBC API to identify this as an SQL {@code TIMESTAMP} value.
 * It adds the ability
 * to hold the SQL {@code TIMESTAMP} fractional seconds value, by allowing
 * the specification of fractional seconds to a precision of nanoseconds.
 * A Timestamp also provides formatting and
 * parsing operations to support the JDBC escape syntax for timestamp values.
 *
 * <p>The precision of a Timestamp object is calculated to be either:
 * <ul>
 * <li>{@code 19 }, which is the number of characters in yyyy-mm-dd hh:mm:ss
 * <li> {@code 20 + s }, which is the number
 * of characters in the yyyy-mm-dd hh:mm:ss.[fff...] and {@code s} represents the scale of the given Timestamp,
 * its fractional seconds precision.
 *</ul>
 *
 * <P><B>Note:</B> This type is a composite of a {@code java.util.Date} and a
 * separate nanoseconds value. Only integral seconds are stored in the
 * {@code java.util.Date} component. The fractional seconds - the nanos - are
 * separate. The {@code Timestamp.equals(Object)} method never returns
 * {@code true} when passed an object
 * that isn't an instance of {@code java.sql.Timestamp},
 * because the nanos component of a date is unknown.
 * As a result, the {@code Timestamp.equals(Object)}
 * method is not symmetric with respect to the
 * {@code java.util.Date.equals(Object)}
 * method. Also, the {@code hashCode} method uses the underlying
 * {@code java.util.Date}
 * implementation and therefore does not include nanos in its computation.
 * <P>
 * Due to the differences between the {@code Timestamp} class
 * and the {@code java.util.Date}
 * class mentioned above, it is recommended that code not view
 * {@code Timestamp} values generically as an instance of
 * {@code java.util.Date}. The
 * inheritance relationship between {@code Timestamp}
 * and {@code java.util.Date} really
 * denotes implementation inheritance, and not type inheritance.
 *
 * @since 1.1
 */
publicclassTimestampextendsjava.util.Date {

/**
 * Constructs a {@code Timestamp} object initialized
 * with the given values.
 *
 * @param year the year minus 1900
 * @param month 0 to 11
 * @param date 1 to 31
 * @param hour 0 to 23
 * @param minute 0 to 59
 * @param second 0 to 59
 * @param nano 0 to 999,999,999
 * @deprecated instead use the constructor {@code Timestamp(long millis)}
 * @throws IllegalArgumentException if the nano argument is out of bounds
 */
@Deprecated(since="1.2")
publicTimestamp(intyear, intmonth, intdate,
inthour, intminute, intsecond, intnano) {
super(year, month, date, hour, minute, second);
if (nano > 999999999 || nano < 0) {
thrownewIllegalArgumentException("nanos > 999999999 or < 0");
 }
nanos = nano;
 }

/**
 * Constructs a {@code Timestamp} object
 * using a milliseconds time value. The
 * integral seconds are stored in the underlying date value; the
 * fractional seconds are stored in the {@code nanos} field of
 * the {@code Timestamp} object.
 *
 * @param time milliseconds since January 1, 1970, 00:00:00 GMT.
 * A negative number is the number of milliseconds before
 * January 1, 1970, 00:00:00 GMT.
 * @see java.util.Calendar
 */
publicTimestamp(longtime) {
super((time/1000)*1000);
nanos = (int)((time%1000) * 1000000);
if (nanos < 0) {
nanos = 1000000000 + nanos;
super.setTime(((time/1000)-1)*1000);
 }
 }

/**
 * Sets this {@code Timestamp} object to represent a point in time that is
 * {@code time} milliseconds after January 1, 1970 00:00:00 GMT.
 *
 * @param time the number of milliseconds.
 * @see #getTime
 * @see #Timestamp(long time)
 * @see java.util.Calendar
 */
publicvoidsetTime(longtime) {
super.setTime((time/1000)*1000);
nanos = (int)((time%1000) * 1000000);
if (nanos < 0) {
nanos = 1000000000 + nanos;
super.setTime(((time/1000)-1)*1000);
 }
 }

/**
 * Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT
 * represented by this {@code Timestamp} object.
 *
 * @return the number of milliseconds since January 1, 1970, 00:00:00 GMT
 * represented by this date.
 * @see #setTime
 */
publiclonggetTime() {
longtime = super.getTime();
return (time + (nanos / 1000000));
 }


/**
 * @serial
 */
privateintnanos;

/**
 * Converts a {@code String} object in JDBC timestamp escape format to a
 * {@code Timestamp} value.
 *
 * @param s timestamp in format {@code yyyy-[m]m-[d]d hh:mm:ss[.f...]}. The
 * fractional seconds may be omitted. The leading zero for {@code mm}
 * and {@code dd} may also be omitted.
 *
 * @return corresponding {@code Timestamp} value
 * @throws java.lang.IllegalArgumentException if the given argument
 * does not have the format {@code yyyy-[m]m-[d]d hh:mm:ss[.f...]}
 */
publicstaticTimestampvalueOf(Strings) {
finalintYEAR_LENGTH = 4;
finalintMONTH_LENGTH = 2;
finalintDAY_LENGTH = 2;
finalintMAX_MONTH = 12;
finalintMAX_DAY = 31;
intyear = 0;
intmonth = 0;
intday = 0;
inthour;
intminute;
intsecond;
inta_nanos = 0;
intfirstDash;
intsecondDash;
intdividingSpace;
intfirstColon;
intsecondColon;
intperiod;
StringformatError = "Timestamp format must be yyyy-mm-dd hh:mm:ss[.fffffffff]";

if (s == null) thrownewjava.lang.IllegalArgumentException("null string");

// Split the string into date and time components
s = s.trim();
dividingSpace = s.indexOf(' ');
if (dividingSpace < 0) {
thrownewjava.lang.IllegalArgumentException(formatError);
 }

// Parse the date
firstDash = s.indexOf('-');
secondDash = s.indexOf('-', firstDash+1);

// Parse the time
firstColon = s.indexOf(':', dividingSpace + 1);
secondColon = s.indexOf(':', firstColon + 1);
period = s.indexOf('.', secondColon + 1);

// Convert the date
booleanparsedDate = false;
if (firstDash > 0 && secondDash > 0 && secondDash < dividingSpace - 1) {
if (firstDash == YEAR_LENGTH &&
 (secondDash - firstDash > 1 && secondDash - firstDash <= MONTH_LENGTH + 1) &&
 (dividingSpace - secondDash > 1 && dividingSpace - secondDash <= DAY_LENGTH + 1)) {
year = Integer.parseInt(s, 0, firstDash, 10);
month = Integer.parseInt(s, firstDash + 1, secondDash, 10);
day = Integer.parseInt(s, secondDash + 1, dividingSpace, 10);

if ((month >= 1 && month <= MAX_MONTH) && (day >= 1 && day <= MAX_DAY)) {
parsedDate = true;
 }
 }
 }
if (! parsedDate) {
thrownewjava.lang.IllegalArgumentException(formatError);
 }

// Convert the time; default missing nanos
intlen = s.length();
if (firstColon > 0 && secondColon > 0 && secondColon < len - 1) {
hour = Integer.parseInt(s, dividingSpace + 1, firstColon, 10);
minute = Integer.parseInt(s, firstColon + 1, secondColon, 10);
if (period > 0 && period < len - 1) {
second = Integer.parseInt(s, secondColon + 1, period, 10);
intnanoPrecision = len - (period + 1);
if (nanoPrecision > 9)
thrownewjava.lang.IllegalArgumentException(formatError);
if (!Character.isDigit(s.charAt(period + 1)))
thrownewjava.lang.IllegalArgumentException(formatError);
inttmpNanos = Integer.parseInt(s, period + 1, len, 10);
while (nanoPrecision < 9) {
tmpNanos *= 10;
nanoPrecision++;
 }
a_nanos = tmpNanos;
 } elseif (period > 0) {
thrownewjava.lang.IllegalArgumentException(formatError);
 } else {
second = Integer.parseInt(s, secondColon + 1, len, 10);
 }
 } else {
thrownewjava.lang.IllegalArgumentException(formatError);
 }

returnnewTimestamp(year - 1900, month - 1, day, hour, minute, second, a_nanos);
 }

/**
 * Formats a timestamp in JDBC timestamp escape format.
 * {@code yyyy-mm-dd hh:mm:ss.fffffffff},
 * where {@code fffffffff} indicates nanoseconds.
 *
 * @return a {@code String} object in
 * {@code yyyy-mm-dd hh:mm:ss.fffffffff} format
 */
@SuppressWarnings("deprecation")
publicStringtoString() {
intyear = super.getYear() + 1900;
intmonth = super.getMonth() + 1;
intday = super.getDate();
inthour = super.getHours();
intminute = super.getMinutes();
intsecond = super.getSeconds();

inttrailingZeros = 0;
inttmpNanos = nanos;
if (tmpNanos == 0) {
trailingZeros = 8;
 } else {
while (tmpNanos % 10 == 0) {
tmpNanos /= 10;
trailingZeros++;
 }
 }

// 8058429: To comply with current JCK tests, we need to deal with year
// being any number between 0 and 292278995
intcount = 10000;
intyearSize = 4;
do {
if (year < count) {
break;
 }
yearSize++;
count *= 10;
 } while (count < 1000000000);

char[] buf = newchar[25 + yearSize - trailingZeros];
Date.formatDecimalInt(year, buf, 0, yearSize);
buf[yearSize] = '-';
Date.formatDecimalInt(month, buf, yearSize + 1, 2);
buf[yearSize + 3] = '-';
Date.formatDecimalInt(day, buf, yearSize + 4, 2);
buf[yearSize + 6] = ' ';
Date.formatDecimalInt(hour, buf, yearSize + 7, 2);
buf[yearSize + 9] = ':';
Date.formatDecimalInt(minute, buf, yearSize + 10, 2);
buf[yearSize + 12] = ':';
Date.formatDecimalInt(second, buf, yearSize + 13, 2);
buf[yearSize + 15] = '.';
Date.formatDecimalInt(tmpNanos, buf, yearSize + 16, 9 - trailingZeros);

returnnewString(buf);
 }

/**
 * Gets this {@code Timestamp} object's {@code nanos} value.
 *
 * @return this {@code Timestamp} object's fractional seconds component
 * @see #setNanos
 */
publicintgetNanos() {
returnnanos;
 }

/**
 * Sets this {@code Timestamp} object's {@code nanos} field
 * to the given value.
 *
 * @param n the new fractional seconds component
 * @throws java.lang.IllegalArgumentException if the given argument
 * is greater than 999999999 or less than 0
 * @see #getNanos
 */
publicvoidsetNanos(intn) {
if (n > 999999999 || n < 0) {
thrownewIllegalArgumentException("nanos > 999999999 or < 0");
 }
nanos = n;
 }

/**
 * Tests to see if this {@code Timestamp} object is
 * equal to the given {@code Timestamp} object.
 *
 * @param ts the {@code Timestamp} value to compare with
 * @return {@code true} if the given {@code Timestamp}
 * object is equal to this {@code Timestamp} object;
 * {@code false} otherwise
 */
publicbooleanequals(Timestampts) {
if (super.equals(ts)) {
if (nanos == ts.nanos) {
returntrue;
 } else {
returnfalse;
 }
 } else {
returnfalse;
 }
 }

/**
 * Tests to see if this {@code Timestamp} object is
 * equal to the given object.
 *
 * This version of the method {@code equals} has been added
 * to fix the incorrect
 * signature of {@code Timestamp.equals(Timestamp)} and to preserve backward
 * compatibility with existing class files.
 *
 * Note: This method is not symmetric with respect to the
 * {@code equals(Object)} method in the base class.
 *
 * @param ts the {@code Object} value to compare with
 * @return {@code true} if the given {@code Object} is an instance
 * of a {@code Timestamp} that
 * is equal to this {@code Timestamp} object;
 * {@code false} otherwise
 */
publicbooleanequals(java.lang.Objectts) {
if (tsinstanceofTimestamp) {
returnthis.equals((Timestamp)ts);
 } else {
returnfalse;
 }
 }

/**
 * Indicates whether this {@code Timestamp} object is
 * earlier than the given {@code Timestamp} object.
 *
 * @param ts the {@code Timestamp} value to compare with
 * @return {@code true} if this {@code Timestamp} object is earlier;
 * {@code false} otherwise
 */
publicbooleanbefore(Timestampts) {
returncompareTo(ts) < 0;
 }

/**
 * Indicates whether this {@code Timestamp} object is
 * later than the given {@code Timestamp} object.
 *
 * @param ts the {@code Timestamp} value to compare with
 * @return {@code true} if this {@code Timestamp} object is later;
 * {@code false} otherwise
 */
publicbooleanafter(Timestampts) {
returncompareTo(ts) > 0;
 }

/**
 * Compares this {@code Timestamp} object to the given
 * {@code Timestamp} object.
 *
 * @param ts the {@code Timestamp} object to be compared to
 * this {@code Timestamp} object
 * @return the value {@code 0} if the two {@code Timestamp}
 * objects are equal; a value less than {@code 0} if this
 * {@code Timestamp} object is before the given argument;
 * and a value greater than {@code 0} if this
 * {@code Timestamp} object is after the given argument.
 * @since 1.4
 */
publicintcompareTo(Timestampts) {
longthisTime = this.getTime();
longanotherTime = ts.getTime();
inti = (thisTime<anotherTime ? -1 :(thisTime==anotherTime?0 :1));
if (i == 0) {
if (nanos > ts.nanos) {
return1;
 } elseif (nanos < ts.nanos) {
return -1;
 }
 }
returni;
 }

/**
 * Compares this {@code Timestamp} object to the given
 * {@code Date} object.
 *
 * @param o the {@code Date} to be compared to
 * this {@code Timestamp} object
 * @return the value {@code 0} if this {@code Timestamp} object
 * and the given object are equal; a value less than {@code 0}
 * if this {@code Timestamp} object is before the given argument;
 * and a value greater than {@code 0} if this
 * {@code Timestamp} object is after the given argument.
 *
 * @since 1.5
 */
publicintcompareTo(java.util.Dateo) {
if(oinstanceofTimestamp) {
// When Timestamp instance compare it with a Timestamp
// Hence it is basically calling this.compareTo((Timestamp))o);
// Note typecasting is safe because o is instance of Timestamp
returncompareTo((Timestamp)o);
 } else {
// When Date doing a o.compareTo(this)
// will give wrong results.
Timestampts = newTimestamp(o.getTime());
returnthis.compareTo(ts);
 }
 }

/**
 * {@inheritDoc}
 *
 * The {@code hashCode} method uses the underlying {@code java.util.Date}
 * implementation and therefore does not include nanos in its computation.
 *
 */
@Override
publicinthashCode() {
returnsuper.hashCode();
 }

staticfinallongserialVersionUID = 2745179027874758501L;

privatestaticfinalintMILLIS_PER_SECOND = 1000;

/**
 * Obtains an instance of {@code Timestamp} from a {@code LocalDateTime}
 * object, with the same year, month, day of month, hours, minutes,
 * seconds and nanos date-time value as the provided {@code LocalDateTime}.
 * <p>
 * The provided {@code LocalDateTime} is interpreted as the local
 * date-time in the local time zone.
 *
 * @param dateTime a {@code LocalDateTime} to convert
 * @return a {@code Timestamp} object
 * @throws NullPointerException if {@code dateTime} is null.
 * @since 1.8
 */
publicstaticTimestampvalueOf(LocalDateTimedateTime) {
returnnewTimestamp(dateTime.getYear() - 1900,
dateTime.getMonthValue() - 1,
dateTime.getDayOfMonth(),
dateTime.getHour(),
dateTime.getMinute(),
dateTime.getSecond(),
dateTime.getNano());
 }

/**
 * Converts this {@code Timestamp} object to a {@code LocalDateTime}.
 * <p>
 * The conversion creates a {@code LocalDateTime} that represents the
 * same year, month, day of month, hours, minutes, seconds and nanos
 * date-time value as this {@code Timestamp} in the local time zone.
 *
 * @return a {@code LocalDateTime} object representing the same date-time value
 * @since 1.8
 */
@SuppressWarnings("deprecation")
publicLocalDateTimetoLocalDateTime() {
returnLocalDateTime.of(getYear() + 1900,
getMonth() + 1,
getDate(),
getHours(),
getMinutes(),
getSeconds(),
getNanos());
 }

/**
 * Obtains an instance of {@code Timestamp} from an {@link Instant} object.
 * <p>
 * {@code Instant} can store points on the time-line further in the future
 * and further in the past than {@code Date}. In this scenario, this method
 * will throw an exception.
 *
 * @param instant the instant to convert
 * @return an {@code Timestamp} representing the same point on the time-line as
 * the provided instant
 * @throws NullPointerException if {@code instant} is null.
 * @throws IllegalArgumentException if the instant is too large to
 * represent as a {@code Timestamp}
 * @since 1.8
 */
publicstaticTimestampfrom(Instantinstant) {
try {
Timestampstamp = newTimestamp(Math.multiplyExact(instant.getEpochSecond(), MILLIS_PER_SECOND));
stamp.nanos = instant.getNano();
returnstamp;
 } catch (ArithmeticExceptionex) {
thrownewIllegalArgumentException(ex);
 }
 }

/**
 * Converts this {@code Timestamp} object to an {@code Instant}.
 * <p>
 * The conversion creates an {@code Instant} that represents the same
 * point on the time-line as this {@code Timestamp}.
 *
 * @return an instant representing the same point on the time-line
 * @since 1.8
 */
@Override
publicInstanttoInstant() {
returnInstant.ofEpochSecond(super.getTime() / MILLIS_PER_SECOND, nanos);
 }
}