Class Timestamps
protobuf/timestamp.proto. All operations throw an
IllegalArgumentException if the input(s) are not valid.-
Nested Class Summary
Nested Classes -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final TimestampA constant holding theTimestampof epoch time,1970-01-01T00:00:00.000000000Z.private static final Methodprivate static final Methodprivate static final Methodstatic final TimestampA constant holding the maximum validTimestamp,9999-12-31T23:59:59.999999999Z.(package private) static final int(package private) static final intstatic final TimestampA constant holding the minimum validTimestamp,0001-01-01T00:00:00Z.(package private) static final int(package private) static final int(package private) static final int(package private) static final long(package private) static final longprivate static final ThreadLocal<SimpleDateFormat> -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic TimestampAdd a duration to a timestamp.static DurationCalculate the difference between two timestamps.static TimestampcheckValid(Timestamp timestamp) Throws anIllegalArgumentExceptionif the givenTimestampis not valid.static TimestampcheckValid(Timestamp.Builder timestampBuilder) Builds the given builder and throws anIllegalArgumentExceptionif it is not valid.static Comparator<Timestamp>Returns aComparatorforTimestampswhich sorts in increasing chronological order.static intCompares two timestamps.private static SimpleDateFormat(package private) static StringformatNanos(int nanos) Format the nano part of a timestamp or a duration.static TimestampCreate a Timestamp from aDate.static TimestampfromMicros(long microseconds) Create a Timestamp from the number of microseconds elapsed from the epoch.static TimestampfromMillis(long milliseconds) Create a Timestamp from the number of milliseconds elapsed from the epoch.static TimestampfromNanos(long nanoseconds) Create a Timestamp from the number of nanoseconds elapsed from the epoch.static TimestampfromSeconds(long seconds) Create a Timestamp from the number of seconds elapsed from the epoch.private static MethodinstantMethod(String methodName) static booleanisValid(long seconds, int nanos) Returns true if the given number of seconds and nanos is a validTimestamp.static booleanReturns true if the givenTimestampis valid.(package private) static TimestampnormalizedTimestamp(long seconds, int nanos) static Timestampnow()Create aTimestampusing the best-available (in terms of precision) system clock.static TimestampParse from RFC 3339 date string to Timestamp.(package private) static intparseNanos(String value) private static longparseTimezoneOffset(String value) static TimestampparseUnchecked(String value) Parses a string in RFC 3339 format into aTimestamp.static TimestampSubtract a duration from a timestamp.static longConvert a Timestamp to the number of microseconds elapsed from the epoch.static longConvert a Timestamp to the number of milliseconds elapsed from the epoch.static longConvert a Timestamp to the number of nanoseconds elapsed from the epoch.static longConvert a Timestamp to the number of seconds elapsed from the epoch.static StringConvert Timestamp to RFC 3339 date string format.
-
Field Details
-
TIMESTAMP_SECONDS_MIN
static final long TIMESTAMP_SECONDS_MIN- See Also:
-
TIMESTAMP_SECONDS_MAX
static final long TIMESTAMP_SECONDS_MAX- See Also:
-
NANOS_PER_SECOND
static final int NANOS_PER_SECOND- See Also:
-
NANOS_PER_MILLISECOND
static final int NANOS_PER_MILLISECOND- See Also:
-
NANOS_PER_MICROSECOND
static final int NANOS_PER_MICROSECOND- See Also:
-
MILLIS_PER_SECOND
static final int MILLIS_PER_SECOND- See Also:
-
MICROS_PER_SECOND
static final int MICROS_PER_SECOND- See Also:
-
MIN_VALUE
A constant holding the minimum validTimestamp,0001-01-01T00:00:00Z. -
MAX_VALUE
A constant holding the maximum validTimestamp,9999-12-31T23:59:59.999999999Z. -
EPOCH
A constant holding theTimestampof epoch time,1970-01-01T00:00:00.000000000Z. -
timestampFormat
-
INSTANT_NOW
-
INSTANT_GET_EPOCH_SECOND
-
INSTANT_GET_NANO
-
-
Constructor Details
-
Timestamps
private Timestamps()
-
-
Method Details
-
createTimestampFormat
-
comparator
Returns aComparatorforTimestampswhich sorts in increasing chronological order. Nulls and invalidTimestampsare not allowed (seeisValid(com.google.protobuf.Timestamp)). The returned comparator is serializable. -
compare
Compares two timestamps. The value returned is identical to what would be returned by:Timestamps.comparator().compare(x, y).- Returns:
- the value
0ifx == y; a value less than0ifx < y; and a value greater than0ifx > y
-
isValid
Returns true if the givenTimestampis valid. Thesecondsvalue 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). Thenanosvalue 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. Thesecondsvalue 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). Thenanosvalue 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.
-
checkValid
Throws anIllegalArgumentExceptionif the givenTimestampis not valid. -
checkValid
Builds the given builder and throws anIllegalArgumentExceptionif it is not valid. SeecheckValid(Timestamp).- Returns:
- A valid, built
Timestamp.
-
toString
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.txtExample of generated format: "1972-01-01T10:00:20.021Z"
- Returns:
- The string representation of the given timestamp.
- Throws:
IllegalArgumentException- if the given timestamp is not in the valid range.
-
parse
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:
ParseException- if parsing fails
-
parseUnchecked
Parses a string in RFC 3339 format into aTimestamp.Identical to
parse(String), but throws anIllegalArgumentExceptioninstead of aParseExceptionif parsing fails.- Returns:
- a
Timestampparsed from the string - Throws:
IllegalArgumentException- if parsing fails
-
instantMethod
-
now
Create aTimestampusing 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
Create a Timestamp from the number of seconds elapsed from the epoch. -
toSeconds
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
Create a Timestamp from the number of milliseconds elapsed from the epoch. -
fromDate
- Throws:
IllegalArgumentException- if the year is before 1 CE or after 9999 CE
-
toMillis
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
Create a Timestamp from the number of microseconds elapsed from the epoch. -
toMicros
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
Create a Timestamp from the number of nanoseconds elapsed from the epoch. -
toNanos
Convert a Timestamp to the number of nanoseconds elapsed from the epoch. -
between
Calculate the difference between two timestamps.Do not use this method for new code. Instead, convert to
Instantusingcom.google.protobuf.util.JavaTimeConversions#toJavaInstant, do the arithmetic there, and convert back usingcom.google.protobuf.util.JavaTimeConversions#toProtoDuration.This method will be deprecated once most uses have been eliminated.
-
add
Add a duration to a timestamp.Do not use this method for new code. Instead, convert to
InstantandDurationusingcom.google.protobuf.util.JavaTimeConversions#toJavaInstantandcom.google.protobuf.util.JavaTimeConversions#toJavaDuration, do the arithmetic there, and convert back usingcom.google.protobuf.util.JavaTimeConversions#toProtoTimestamp.This method will be deprecated once most uses have been eliminated.
-
subtract
Subtract a duration from a timestamp.Do not use this method for new code. Instead, convert to
InstantandDurationusingcom.google.protobuf.util.JavaTimeConversions#toJavaInstantandcom.google.protobuf.util.JavaTimeConversions#toJavaDuration, do the arithmetic there, and convert back usingcom.google.protobuf.util.JavaTimeConversions#toProtoTimestamp.This method will be deprecated once most uses have been eliminated.
-
normalizedTimestamp
-
parseTimezoneOffset
- Throws:
ParseException
-
parseNanos
- Throws:
ParseException
-
formatNanos
Format the nano part of a timestamp or a duration.
-