Class Timestamps
- java.lang.Object
-
- com.google.protobuf.util.Timestamps
-
public final class Timestamps extends java.lang.Object
Utilities to help create/manipulateprotobuf/timestamp.proto
. All operations throw anIllegalArgumentException
if the input(s) are not valid.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
Timestamps.TimestampComparator
-
Field Summary
Fields Modifier and Type Field Description static Timestamp
EPOCH
A constant holding theTimestamp
of epoch time,1970-01-01T00:00:00.000000000Z
.private static java.lang.reflect.Method
INSTANT_GET_EPOCH_SECOND
private static java.lang.reflect.Method
INSTANT_GET_NANO
private static java.lang.reflect.Method
INSTANT_NOW
static Timestamp
MAX_VALUE
A constant holding the maximum validTimestamp
,9999-12-31T23:59:59.999999999Z
.(package private) static int
MICROS_PER_SECOND
(package private) static int
MILLIS_PER_SECOND
static Timestamp
MIN_VALUE
A constant holding the minimum validTimestamp
,0001-01-01T00:00:00Z
.(package private) static int
NANOS_PER_MICROSECOND
(package private) static int
NANOS_PER_MILLISECOND
(package private) static int
NANOS_PER_SECOND
(package private) static long
TIMESTAMP_SECONDS_MAX
(package private) static long
TIMESTAMP_SECONDS_MIN
private static java.lang.ThreadLocal<java.text.SimpleDateFormat>
timestampFormat
-
Constructor Summary
Constructors Modifier Constructor Description private
Timestamps()
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static Timestamp
add(Timestamp start, Duration length)
Add a duration to a timestamp.static Duration
between(Timestamp from, Timestamp to)
Calculate the difference between two timestamps.static Timestamp
checkValid(Timestamp timestamp)
Throws anIllegalArgumentException
if the givenTimestamp
is not valid.static Timestamp
checkValid(Timestamp.Builder timestampBuilder)
Builds the given builder and throws anIllegalArgumentException
if it is not valid.static java.util.Comparator<Timestamp>
comparator()
Returns aComparator
forTimestamps
which sorts in increasing chronological order.static int
compare(Timestamp x, Timestamp y)
Compares two timestamps.private static java.text.SimpleDateFormat
createTimestampFormat()
(package private) static java.lang.String
formatNanos(int nanos)
Format the nano part of a timestamp or a duration.static Timestamp
fromDate(java.util.Date date)
Create a Timestamp from aDate
.static Timestamp
fromMicros(long microseconds)
Create a Timestamp from the number of microseconds elapsed from the epoch.static Timestamp
fromMillis(long milliseconds)
Create a Timestamp from the number of milliseconds elapsed from the epoch.static Timestamp
fromNanos(long nanoseconds)
Create a Timestamp from the number of nanoseconds elapsed from the epoch.static Timestamp
fromSeconds(long seconds)
Create a Timestamp from the number of seconds elapsed from the epoch.private static java.lang.reflect.Method
instantMethod(java.lang.String methodName)
static boolean
isValid(long seconds, int nanos)
Returns true if the given number of seconds and nanos is a validTimestamp
.static boolean
isValid(Timestamp timestamp)
Returns true if the givenTimestamp
is valid.private static boolean
isValidSeconds(long seconds)
Returns true if the given number of seconds is valid, if combined with a valid number of nanos.(package private) static Timestamp
normalizedTimestamp(long seconds, int nanos)
static Timestamp
now()
Create aTimestamp
using the best-available (in terms of precision) system clock.static Timestamp
parse(java.lang.String value)
Parse from RFC 3339 date string to Timestamp.(package private) static int
parseNanos(java.lang.String value)
private static long
parseTimezoneOffset(java.lang.String value)
static Timestamp
parseUnchecked(java.lang.String value)
Parses a string in RFC 3339 format into aTimestamp
.static Timestamp
subtract(Timestamp start, Duration length)
Subtract a duration from a timestamp.static long
toMicros(Timestamp timestamp)
Convert a Timestamp to the number of microseconds elapsed from the epoch.static long
toMillis(Timestamp timestamp)
Convert a Timestamp to the number of milliseconds elapsed from the epoch.static long
toNanos(Timestamp timestamp)
Convert a Timestamp to the number of nanoseconds elapsed from the epoch.static long
toSeconds(Timestamp timestamp)
Convert a Timestamp to the number of seconds elapsed from the epoch.static java.lang.String
toString(Timestamp timestamp)
Convert Timestamp to RFC 3339 date string format.
-
-
-
Field Detail
-
TIMESTAMP_SECONDS_MIN
static final long TIMESTAMP_SECONDS_MIN
- See Also:
- Constant Field Values
-
TIMESTAMP_SECONDS_MAX
static final long TIMESTAMP_SECONDS_MAX
- See Also:
- Constant Field Values
-
NANOS_PER_SECOND
static final int NANOS_PER_SECOND
- See Also:
- Constant Field Values
-
NANOS_PER_MILLISECOND
static final int NANOS_PER_MILLISECOND
- See Also:
- Constant Field Values
-
NANOS_PER_MICROSECOND
static final int NANOS_PER_MICROSECOND
- See Also:
- Constant Field Values
-
MILLIS_PER_SECOND
static final int MILLIS_PER_SECOND
- See Also:
- Constant Field Values
-
MICROS_PER_SECOND
static final int MICROS_PER_SECOND
- See Also:
- Constant Field Values
-
MIN_VALUE
public static final Timestamp MIN_VALUE
A constant holding the minimum validTimestamp
,0001-01-01T00:00:00Z
.
-
MAX_VALUE
public static final Timestamp MAX_VALUE
A constant holding the maximum validTimestamp
,9999-12-31T23:59:59.999999999Z
.
-
EPOCH
public static final Timestamp EPOCH
A constant holding theTimestamp
of epoch time,1970-01-01T00:00:00.000000000Z
.
-
timestampFormat
private static final java.lang.ThreadLocal<java.text.SimpleDateFormat> timestampFormat
-
INSTANT_NOW
@Nullable private static final java.lang.reflect.Method INSTANT_NOW
-
INSTANT_GET_EPOCH_SECOND
@Nullable private static final java.lang.reflect.Method INSTANT_GET_EPOCH_SECOND
-
INSTANT_GET_NANO
@Nullable private static final java.lang.reflect.Method INSTANT_GET_NANO
-
-
Method Detail
-
createTimestampFormat
private static java.text.SimpleDateFormat createTimestampFormat()
-
comparator
public static java.util.Comparator<Timestamp> comparator()
Returns aComparator
forTimestamps
which sorts in increasing chronological order. Nulls and invalidTimestamps
are not allowed (seeisValid(com.google.protobuf.Timestamp)
). The returned comparator is serializable.
-
compare
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)
.- Returns:
- the value
0
ifx == y
; a value less than0
ifx < y
; and a value greater than0
ifx > y
-
isValid
public static boolean isValid(Timestamp timestamp)
Returns true if the givenTimestamp
is valid. Theseconds
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). Thenanos
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.
-
isValid
public static boolean isValid(long seconds, int nanos)
Returns true if the given number of seconds and nanos is a validTimestamp
. Theseconds
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). Thenanos
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.
-
isValidSeconds
private static boolean isValidSeconds(long seconds)
Returns true if the given number of seconds is valid, if combined with a valid number of nanos. Theseconds
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).
-
checkValid
@CanIgnoreReturnValue public static Timestamp checkValid(Timestamp timestamp)
Throws anIllegalArgumentException
if the givenTimestamp
is not valid.
-
checkValid
public static Timestamp checkValid(Timestamp.Builder timestampBuilder)
Builds the given builder and throws anIllegalArgumentException
if it is not valid. SeecheckValid(Timestamp)
.- Returns:
- A valid, built
Timestamp
.
-
toString
public static java.lang.String toString(Timestamp timestamp)
Convert Timestamp to RFC 3339 date string format. The output will always be Z-normalized and uses 0, 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.txtExample of generated format: "1972-01-01T10:00:20.021Z"
- Returns:
- The string representation of the given timestamp.
- Throws:
java.lang.IllegalArgumentException
- if the given timestamp is not in the valid range.
-
parse
public static Timestamp parse(java.lang.String value) throws java.text.ParseException
Parse from RFC 3339 date string to Timestamp. This method accepts all outputs oftoString(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"
- Returns:
- a Timestamp parsed from the string
- Throws:
java.text.ParseException
- if parsing fails
-
parseUnchecked
public static Timestamp parseUnchecked(@CompileTimeConstant java.lang.String value)
Parses a string in RFC 3339 format into aTimestamp
.Identical to
parse(String)
, but throws anIllegalArgumentException
instead of aParseException
if parsing fails.- Returns:
- a
Timestamp
parsed from the string - Throws:
java.lang.IllegalArgumentException
- if parsing fails
-
instantMethod
@Nullable private static java.lang.reflect.Method instantMethod(java.lang.String methodName)
-
now
public static Timestamp now()
Create aTimestamp
using the best-available (in terms of precision) system clock.Note: that while this API is convenient, it may harm the testability of your code, as you're unable to mock the current time. Instead, you may want to consider injecting a clock instance to read the current time.
-
fromSeconds
public static Timestamp fromSeconds(long seconds)
Create a Timestamp from the number of seconds elapsed from the epoch.
-
toSeconds
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.
-
fromMillis
public static Timestamp fromMillis(long milliseconds)
Create a Timestamp from the number of milliseconds elapsed from the epoch.
-
fromDate
@J2ObjCIncompatible public static Timestamp fromDate(java.util.Date date)
Create a Timestamp from aDate
. If theDate
is aTimestamp
, full nanonsecond precision is retained.- Throws:
java.lang.IllegalArgumentException
- if the year is before 1 CE or after 9999 CE
-
toMillis
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. For instance, if the timestamp represents "1969-12-31T23:59:59.999999999Z", it will be rounded to -1 millisecond.
-
fromMicros
public static Timestamp fromMicros(long microseconds)
Create a Timestamp from the number of microseconds elapsed from the epoch.
-
toMicros
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.
-
fromNanos
public static Timestamp fromNanos(long nanoseconds)
Create a Timestamp from the number of nanoseconds elapsed from the epoch.
-
toNanos
public static long toNanos(Timestamp timestamp)
Convert a Timestamp to the number of nanoseconds elapsed from the epoch.
-
between
public static Duration between(Timestamp from, Timestamp to)
Calculate the difference between two timestamps.
-
subtract
public static Timestamp subtract(Timestamp start, Duration length)
Subtract a duration from a timestamp.
-
normalizedTimestamp
static Timestamp normalizedTimestamp(long seconds, int nanos)
-
parseTimezoneOffset
private static long parseTimezoneOffset(java.lang.String value) throws java.text.ParseException
- Throws:
java.text.ParseException
-
parseNanos
static int parseNanos(java.lang.String value) throws java.text.ParseException
- Throws:
java.text.ParseException
-
formatNanos
static java.lang.String formatNanos(int nanos)
Format the nano part of a timestamp or a duration.
-
-