Module java.sql
Package java.sql

## Class Timestamp

- java.lang.Object
- - java.util.Date
  - - java.sql.Timestamp

- All Implemented Interfaces:
    `Serializable`, `Cloneable`, `Comparable<Date>`

      public class Timestamp
      extends Date

  A thin wrapper around `java.util.Date` that allows the JDBC API to identify this as an SQL `TIMESTAMP` value. It adds the ability to hold the SQL `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.

  The precision of a Timestamp object is calculated to be either:

  - `19` , which is the number of characters in yyyy-mm-dd hh:mm:ss
  - `20 + s` , which is the number of characters in the yyyy-mm-dd hh:mm:ss.[fff...] and `s` represents the scale of the given Timestamp, its fractional seconds precision.

  Note: This type is a composite of a `java.util.Date` and a separate nanoseconds value. Only integral seconds are stored in the `java.util.Date` component. The fractional seconds - the nanos - are separate. The `Timestamp.equals(Object)` method never returns `true` when passed an object that isn't an instance of `java.sql.Timestamp`, because the nanos component of a date is unknown. As a result, the `Timestamp.equals(Object)` method is not symmetric with respect to the `java.util.Date.equals(Object)` method. Also, the `hashCode` method uses the underlying `java.util.Date` implementation and therefore does not include nanos in its computation.

  Due to the differences between the `Timestamp` class and the `java.util.Date` class mentioned above, it is recommended that code not view `Timestamp` values generically as an instance of `java.util.Date`. The inheritance relationship between `Timestamp` and `java.util.Date` really denotes implementation inheritance, and not type inheritance.

  Since:
    1.1
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Timestamp​(int year, int month, int date, int hour, int minute, int second, int nano)` | Deprecated. instead use the constructor `Timestamp(long millis)`
    `Timestamp​(long time)` | Constructs a `Timestamp` object using a milliseconds time value.

  - ### Method Summary

    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `after​(Timestamp ts)` | Indicates whether this `Timestamp` object is later than the given `Timestamp` object.
    `boolean` | `before​(Timestamp ts)` | Indicates whether this `Timestamp` object is earlier than the given `Timestamp` object.
    `int` | `compareTo​(Timestamp ts)` | Compares this `Timestamp` object to the given `Timestamp` object.
    `int` | `compareTo​(Date o)` | Compares this `Timestamp` object to the given `Date` object.
    `boolean` | `equals​(Object ts)` | Tests to see if this `Timestamp` object is equal to the given object.
    `boolean` | `equals​(Timestamp ts)` | Tests to see if this `Timestamp` object is equal to the given `Timestamp` object.
    `static Timestamp` | `from​(Instant instant)` | Obtains an instance of `Timestamp` from an `Instant` object.
    `int` | `getNanos()` | Gets this `Timestamp` object's `nanos` value.
    `long` | `getTime()` | Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by this `Timestamp` object.
    `int` | `hashCode()` | Returns a hash code value for this object.
    `void` | `setNanos​(int n)` | Sets this `Timestamp` object's `nanos` field to the given value.
    `void` | `setTime​(long time)` | Sets this `Timestamp` object to represent a point in time that is `time` milliseconds after January 1, 1970 00:00:00 GMT.
    `Instant` | `toInstant()` | Converts this `Timestamp` object to an `Instant`.
    `LocalDateTime` | `toLocalDateTime()` | Converts this `Timestamp` object to a `LocalDateTime`.
    `String` | `toString()` | Formats a timestamp in JDBC timestamp escape format.
    `static Timestamp` | `valueOf​(String s)` | Converts a `String` object in JDBC timestamp escape format to a `Timestamp` value.
    `static Timestamp` | `valueOf​(LocalDateTime dateTime)` | Obtains an instance of `Timestamp` from a `LocalDateTime` object, with the same year, month, day of month, hours, minutes, seconds and nanos date-time value as the provided `LocalDateTime`.

    - ### Methods declared in class java.util.Date

      `after, before, clone, getDate, getDay, getHours, getMinutes, getMonth, getSeconds, getTimezoneOffset, getYear, parse, setDate, setHours, setMinutes, setMonth, setSeconds, setYear, toGMTString, toLocaleString, UTC`

    - ### Methods declared in class java.lang.Object

      `finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Timestamp

          @Deprecated(since="1.2")
          public Timestamp​(int year,
                           int month,
                           int date,
                           int hour,
                           int minute,
                           int second,
                           int nano)

      Deprecated.
      instead use the constructor `Timestamp(long millis)`
      Constructs a `Timestamp` object initialized with the given values.
      Parameters:
        `year` - the year minus 1900
        `month` - 0 to 11
        `date` - 1 to 31
        `hour` - 0 to 23
        `minute` - 0 to 59
        `second` - 0 to 59
        `nano` - 0 to 999,999,999
      Throws:
        `IllegalArgumentException` - if the nano argument is out of bounds

    - #### Timestamp

          public Timestamp​(long time)

      Constructs a `Timestamp` object using a milliseconds time value. The integral seconds are stored in the underlying date value; the fractional seconds are stored in the `nanos` field of the `Timestamp` object.
      Parameters:
        `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 Also:
        `Calendar`

  - ### Method Detail

    - #### setTime

          public void setTime​(long time)

      Sets this `Timestamp` object to represent a point in time that is `time` milliseconds after January 1, 1970 00:00:00 GMT.
      Overrides:
        `setTime` in class `Date`
      Parameters:
        `time` - the number of milliseconds.
      See Also:
        `getTime()`, `Timestamp(long time)`, `Calendar`

    - #### getTime

          public long getTime()

      Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by this `Timestamp` object.
      Overrides:
        `getTime` in class `Date`
      Returns:
        the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by this date.
      See Also:
        `setTime(long)`

    - #### valueOf

          public static Timestamp valueOf​(String s)

      Converts a `String` object in JDBC timestamp escape format to a `Timestamp` value.
      Parameters:
        `s` - timestamp in format `yyyy-[m]m-[d]d hh:mm:ss[.f...]`. The fractional seconds may be omitted. The leading zero for `mm` and `dd` may also be omitted.
      Returns:
        corresponding `Timestamp` value
      Throws:
        `IllegalArgumentException` - if the given argument does not have the format `yyyy-[m]m-[d]d hh:mm:ss[.f...]`

    - #### toString

          public String toString()

      Formats a timestamp in JDBC timestamp escape format. `yyyy-mm-dd hh:mm:ss.fffffffff`, where `fffffffff` indicates nanoseconds.
      Overrides:
        `toString` in class `Date`
      Returns:
        a `String` object in `yyyy-mm-dd hh:mm:ss.fffffffff` format
      See Also:
        `Date.toLocaleString()`, `Date.toGMTString()`

    - #### getNanos

          public int getNanos()

      Gets this `Timestamp` object's `nanos` value.
      Returns:
        this `Timestamp` object's fractional seconds component
      See Also:
        `setNanos(int)`

    - #### setNanos

          public void setNanos​(int n)

      Sets this `Timestamp` object's `nanos` field to the given value.
      Parameters:
        `n` - the new fractional seconds component
      Throws:
        `IllegalArgumentException` - if the given argument is greater than 999999999 or less than 0
      See Also:
        `getNanos()`

    - #### equals

          public boolean equals​(Timestamp ts)

      Tests to see if this `Timestamp` object is equal to the given `Timestamp` object.
      Parameters:
        `ts` - the `Timestamp` value to compare with
      Returns:
        `true` if the given `Timestamp` object is equal to this `Timestamp` object; `false` otherwise

    - #### equals

          public boolean equals​(Object ts)

      Tests to see if this `Timestamp` object is equal to the given object. This version of the method `equals` has been added to fix the incorrect signature of `Timestamp.equals(Timestamp)` and to preserve backward compatibility with existing class files. Note: This method is not symmetric with respect to the `equals(Object)` method in the base class.
      Overrides:
        `equals` in class `Date`
      Parameters:
        `ts` - the `Object` value to compare with
      Returns:
        `true` if the given `Object` is an instance of a `Timestamp` that is equal to this `Timestamp` object; `false` otherwise
      See Also:
        `Date.getTime()`

    - #### before

          public boolean before​(Timestamp ts)

      Indicates whether this `Timestamp` object is earlier than the given `Timestamp` object.
      Parameters:
        `ts` - the `Timestamp` value to compare with
      Returns:
        `true` if this `Timestamp` object is earlier; `false` otherwise

    - #### after

          public boolean after​(Timestamp ts)

      Indicates whether this `Timestamp` object is later than the given `Timestamp` object.
      Parameters:
        `ts` - the `Timestamp` value to compare with
      Returns:
        `true` if this `Timestamp` object is later; `false` otherwise

    - #### compareTo

          public int compareTo​(Timestamp ts)

      Compares this `Timestamp` object to the given `Timestamp` object.
      Parameters:
        `ts` - the `Timestamp` object to be compared to this `Timestamp` object
      Returns:
        the value `0` if the two `Timestamp` objects are equal; a value less than `0` if this `Timestamp` object is before the given argument; and a value greater than `0` if this `Timestamp` object is after the given argument.
      Since:
        1.4

    - #### compareTo

          public int compareTo​(Date o)

      Compares this `Timestamp` object to the given `Date` object.
      Specified by:
        `compareTo` in interface `Comparable<Date>`
      Overrides:
        `compareTo` in class `Date`
      Parameters:
        `o` - the `Date` to be compared to this `Timestamp` object
      Returns:
        the value `0` if this `Timestamp` object and the given object are equal; a value less than `0` if this `Timestamp` object is before the given argument; and a value greater than `0` if this `Timestamp` object is after the given argument.
      Since:
        1.5

    - #### hashCode

          public int hashCode()

      Returns a hash code value for this object. The result is the exclusive OR of the two halves of the primitive `long` value returned by the `Date.getTime()` method. That is, the hash code is the value of the expression:

      >      (int)(this.getTime()^(this.getTime() >>> 32))

      The `hashCode` method uses the underlying `java.util.Date` implementation and therefore does not include nanos in its computation.
      Overrides:
        `hashCode` in class `Date`
      Returns:
        a hash code value for this object.
      See Also:
        `Object.equals(java.lang.Object)`, `System.identityHashCode(java.lang.Object)`

    - #### valueOf

          public static Timestamp valueOf​(LocalDateTime dateTime)

      Obtains an instance of `Timestamp` from a `LocalDateTime` object, with the same year, month, day of month, hours, minutes, seconds and nanos date-time value as the provided `LocalDateTime`.

      The provided `LocalDateTime` is interpreted as the local date-time in the local time zone.

      Parameters:
        `dateTime` - a `LocalDateTime` to convert
      Returns:
        a `Timestamp` object
      Throws:
        `NullPointerException` - if `dateTime` is null.
      Since:
        1.8

    - #### toLocalDateTime

          public LocalDateTime toLocalDateTime()

      Converts this `Timestamp` object to a `LocalDateTime`.

      The conversion creates a `LocalDateTime` that represents the same year, month, day of month, hours, minutes, seconds and nanos date-time value as this `Timestamp` in the local time zone.

      Returns:
        a `LocalDateTime` object representing the same date-time value
      Since:
        1.8

    - #### from

          public static Timestamp from​(Instant instant)

      Obtains an instance of `Timestamp` from an `Instant` object.

      `Instant` can store points on the time-line further in the future and further in the past than `Date`. In this scenario, this method will throw an exception.

      Parameters:
        `instant` - the instant to convert
      Returns:
        an `Timestamp` representing the same point on the time-line as the provided instant
      Throws:
        `NullPointerException` - if `instant` is null.
        `IllegalArgumentException` - if the instant is too large to represent as a `Timestamp`
      Since:
        1.8

    - #### toInstant

          public Instant toInstant()

      Converts this `Timestamp` object to an `Instant`.

      The conversion creates an `Instant` that represents the same point on the time-line as this `Timestamp`.

      Overrides:
        `toInstant` in class `Date`
      Returns:
        an instant representing the same point on the time-line
      Since:
        1.8