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...] ands
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
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 |
Method Summary
Modifier and Type | Method | Description |
---|---|---|
boolean | after(Timestamp ts) | Indicates whether this |
boolean | before(Timestamp ts) | Indicates whether this |
int | compareTo(Timestamp ts) | Compares this |
int | compareTo(Date o) | Compares this |
boolean | equals(Object ts) | Tests to see if this |
boolean | equals(Timestamp ts) | Tests to see if this |
static Timestamp | from(Instant instant) | Obtains an instance of |
int | getNanos() | Gets this |
long | getTime() | Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by this |
int | hashCode() | Returns a hash code value for this object. |
void | setNanos(int n) | Sets this |
void | setTime(long time) | Sets this |
Instant | toInstant() | Converts this |
LocalDateTime | toLocalDateTime() | Converts this |
String | toString() | Formats a timestamp in JDBC timestamp escape format. |
static Timestamp | valueOf(String s) | Converts a |
static Timestamp | valueOf(LocalDateTime dateTime) | Obtains an instance of |
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)
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 classDate
- 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 classDate
- 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 formatyyyy-[m]m-[d]d hh:mm:ss[.f...]
. The fractional seconds may be omitted. The leading zero formm
anddd
may also be omitted. - Returns:
- corresponding
Timestamp
value - Throws:
-
IllegalArgumentException
- if the given argument does not have the formatyyyy-[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 classDate
- Returns:
- a
String
object inyyyy-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
- theTimestamp
value to compare with - Returns:
-
true
if the givenTimestamp
object is equal to thisTimestamp
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 classDate
- Parameters:
-
ts
- theObject
value to compare with - Returns:
-
true
if the givenObject
is an instance of aTimestamp
that is equal to thisTimestamp
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
- theTimestamp
value to compare with - Returns:
-
true
if thisTimestamp
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
- theTimestamp
value to compare with - Returns:
-
true
if thisTimestamp
object is later;false
otherwise
compareTo
public int compareTo(Timestamp ts)
Compares this Timestamp
object to the given Timestamp
object.
- Parameters:
-
ts
- theTimestamp
object to be compared to thisTimestamp
object - Returns:
- the value
0
if the twoTimestamp
objects are equal; a value less than0
if thisTimestamp
object is before the given argument; and a value greater than0
if thisTimestamp
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 interfaceComparable<Date>
- Overrides:
-
compareTo
in classDate
- Parameters:
-
o
- theDate
to be compared to thisTimestamp
object - Returns:
- the value
0
if thisTimestamp
object and the given object are equal; a value less than0
if thisTimestamp
object is before the given argument; and a value greater than0
if thisTimestamp
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 classDate
- 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
- aLocalDateTime
to convert - Returns:
- a
Timestamp
object - Throws:
-
NullPointerException
- ifdateTime
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
- ifinstant
is null. -
IllegalArgumentException
- if the instant is too large to represent as aTimestamp
- 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
.