Class Timestamps (3.19.4)

public final class Timestamps

Utilities to help create/manipulate protobuf/timestamp.proto. All operations throw an IllegalArgumentException if the input(s) are not valid.

Inheritance

java.lang.Object > Timestamps

Inherited Members

Object.clone()

Object.equals(Object)

Object.finalize()

Object.getClass()

Object.hashCode()

Object.notify()

Object.notifyAll()

Object.toString()

Object.wait()

Object.wait(long)

Object.wait(long,int)

Static Fields

EPOCH

public static final Timestamp EPOCH

A constant holding the Timestamp of epoch time, 1970-01-01T00:00:00.000000000Z.

Field Value
Type	Description
Timestamp

MAX_VALUE

public static final Timestamp MAX_VALUE

A constant holding the maximum valid Timestamp, 9999-12-31T23:59:59.999999999Z.

Field Value
Type	Description
Timestamp

MIN_VALUE

public static final Timestamp MIN_VALUE

A constant holding the minimum valid Timestamp, 0001-01-01T00:00:00Z.

Field Value
Type	Description
Timestamp

Static Methods

add(Timestamp start, Duration length)

public static Timestamp add(Timestamp start, Duration length)

Add a duration to a timestamp.

Parameters
Name	Description
start	Timestamp
length	Duration

Returns
Type	Description
Timestamp

between(Timestamp from, Timestamp to)

public static Duration between(Timestamp from, Timestamp to)

Calculate the difference between two timestamps.

Parameters
Name	Description
from	Timestamp
to	Timestamp

Returns
Type	Description
Duration

checkValid(Timestamp timestamp)

public static Timestamp checkValid(Timestamp timestamp)

Throws an IllegalArgumentException if the given Timestamp is not valid.

Parameter
Name	Description
timestamp	Timestamp

Returns
Type	Description
Timestamp

checkValid(Timestamp.Builder timestampBuilder)

public static Timestamp checkValid(Timestamp.Builder timestampBuilder)

Builds the given builder and throws an IllegalArgumentException if it is not valid. See #checkValid(Timestamp).

Parameter
Name	Description
timestampBuilder	Timestamp.Builder

Returns
Type	Description
Timestamp	A valid, built Timestamp.

comparator()

public static Comparator<Timestamp> comparator()

Returns a Comparator for Timestamps which sorts in increasing chronological order. Nulls and invalid Timestamps are not allowed (see #isValid). The returned comparator is serializable.

Returns
Type	Description
Comparator<Timestamp>

compare(Timestamp x, Timestamp y)

public static int compare(Timestamp x, Timestamp y)

Compares two timestamps. The value returned is identical to what would be returned by: Timestamps.comparator().compare(x, y).

Parameters
Name	Description
x	Timestamp
y	Timestamp

Returns
Type	Description
int	the value 0 if x == y; a value less than 0 if x < y; and a value greater than 0 if x > y

fromDate(Date date)

public static Timestamp fromDate(Date date)

Create a Timestamp from a java.util.Date. If the java.util.Date is a java.sql.Timestamp, full nanonsecond precision is retained.

Parameter
Name	Description
date	Date

Returns
Type	Description
Timestamp

fromMicros(long microseconds)

public static Timestamp fromMicros(long microseconds)

Create a Timestamp from the number of microseconds elapsed from the epoch.

Parameter
Name	Description
microseconds	long

Returns
Type	Description
Timestamp

fromMillis(long milliseconds)

public static Timestamp fromMillis(long milliseconds)

Create a Timestamp from the number of milliseconds elapsed from the epoch.

Parameter
Name	Description
milliseconds	long

Returns
Type	Description
Timestamp

fromNanos(long nanoseconds)

public static Timestamp fromNanos(long nanoseconds)

Create a Timestamp from the number of nanoseconds elapsed from the epoch.

Parameter
Name	Description
nanoseconds	long

Returns
Type	Description
Timestamp

fromSeconds(long seconds)

public static Timestamp fromSeconds(long seconds)

Create a Timestamp from the number of seconds elapsed from the epoch.

Parameter
Name	Description
seconds	long

Returns
Type	Description
Timestamp

isValid(Timestamp timestamp)

public static boolean isValid(Timestamp timestamp)

Returns true if the given Timestamp is valid. The seconds value must be in the range [-62,135,596,800, +253,402,300,799] (i.e., between 0001-01-01T00:00:00Z and 9999-12-31T23:59:59Z). The nanos value must be in the range [0, +999,999,999].

Note: Negative second values with fractional seconds must still have non-negative nanos values that count forward in time.

Parameter
Name	Description
timestamp	Timestamp

Returns
Type	Description
boolean

isValid(long seconds, int nanos)

public static boolean isValid(long seconds, int nanos)

Returns true if the given number of seconds and nanos is a valid Timestamp. The seconds value must be in the range [-62,135,596,800, +253,402,300,799] (i.e., between 0001-01-01T00:00:00Z and 9999-12-31T23:59:59Z). The nanos value must be in the range [0, +999,999,999].

Note: Negative second values with fractional seconds must still have non-negative nanos values that count forward in time.

Parameters
Name	Description
seconds	long
nanos	int

Returns
Type	Description
boolean

parse(String value)

public static Timestamp parse(String value)

Parse from RFC 3339 date string to Timestamp. This method accepts all outputs of #toString(Timestamp) and it also accepts any fractional digits (or none) and any offset as long as they fit into nano-seconds precision.

Example of accepted format: "1972-01-01T10:00:20.021-05:00"

Parameter
Name	Description
value	String

Returns
Type	Description
Timestamp	A Timestamp parsed from the string.

Exceptions
Type	Description
ParseException	if parsing fails.

parseUnchecked(String value)

public static Timestamp parseUnchecked(String value)

Parses a string in RFC 3339 format into a Timestamp.

Identical to #parse(String), but throws an IllegalArgumentException instead of a ParseException if parsing fails.

Parameter
Name	Description
value	String

Returns
Type	Description
Timestamp	a Timestamp parsed from the string

subtract(Timestamp start, Duration length)

public static Timestamp subtract(Timestamp start, Duration length)

Subtract a duration from a timestamp.

Parameters
Name	Description
start	Timestamp
length	Duration

Returns
Type	Description
Timestamp

toMicros(Timestamp timestamp)

public static long toMicros(Timestamp timestamp)

Convert a Timestamp to the number of microseconds elapsed from the epoch.

The result will be rounded down to the nearest microsecond. E.g., if the timestamp represents "1969-12-31T23:59:59.999999999Z", it will be rounded to -1 microsecond.

Parameter
Name	Description
timestamp	Timestamp

Returns
Type	Description
long

toMillis(Timestamp timestamp)

public static long toMillis(Timestamp timestamp)

Convert a Timestamp to the number of milliseconds elapsed from the epoch.

The result will be rounded down to the nearest millisecond. E.g., if the timestamp represents "1969-12-31T23:59:59.999999999Z", it will be rounded to -1 millisecond.

Parameter
Name	Description
timestamp	Timestamp

Returns
Type	Description
long

toNanos(Timestamp timestamp)

public static long toNanos(Timestamp timestamp)

Convert a Timestamp to the number of nanoseconds elapsed from the epoch.

Parameter
Name	Description
timestamp	Timestamp

Returns
Type	Description
long

toSeconds(Timestamp timestamp)

public static long toSeconds(Timestamp timestamp)

Convert a Timestamp to the number of seconds elapsed from the epoch.

The result will be rounded down to the nearest second. E.g., if the timestamp represents "1969-12-31T23:59:59.999999999Z", it will be rounded to -1 second.

Parameter
Name	Description
timestamp	Timestamp

Returns
Type	Description
long

toString(Timestamp timestamp)

public static String toString(Timestamp timestamp)

Convert Timestamp to RFC 3339 date string format. The output will always be Z-normalized and uses 3, 6 or 9 fractional digits as required to represent the exact value. Note that Timestamp can only represent time from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. See https://www.ietf.org/rfc/rfc3339.txt

Example of generated format: "1972-01-01T10:00:20.021Z"

Parameter
Name	Description
timestamp	Timestamp

Returns
Type	Description
String	The string representation of the given timestamp.