Package com.google.protobuf.util

Class Timestamps

java.lang.Object
com.google.protobuf.util.Timestamps
public final class Timestamps extends Object
Utilities to help create/manipulate protobuf/timestamp.proto. All operations throw an IllegalArgumentException if the input(s) are not valid.

  • Field Details

    • MIN_VALUE

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

    • MAX_VALUE

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

    • EPOCH

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

  • Method Details

    • 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(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 if x == y; a value less than 0 if x < y; and a value greater than 0 if x > y

    • isValid

      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.

    • isValid

      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.

    • checkValid

      @CanIgnoreReturnValue public static Timestamp checkValid(Timestamp timestamp)
      Throws an IllegalArgumentException if the given Timestamp is not valid.

    • checkValid

      public static Timestamp checkValid(Timestamp.Builder timestampBuilder)
      Builds the given builder and throws an IllegalArgumentException if it is not valid. See checkValid(Timestamp).
      Returns:
      A valid, built Timestamp.

    • toString

      public static 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.txt

      Example 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

      public static Timestamp parse(String value) throws ParseException
      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"

      Returns:
      a Timestamp parsed from the string
      Throws:
      ParseException - if parsing fails

    • parseUnchecked

      public static Timestamp parseUnchecked(@CompileTimeConstant 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.

      Returns:
      a Timestamp parsed from the string
      Throws:
      IllegalArgumentException - if parsing fails

    • now

      public static Timestamp now()
      Create a Timestamp 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(Date date)
      Create a Timestamp from a Date. If the Date is a Timestamp, full nanonsecond precision is retained.
      Throws:
      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.

    • add

      public static Timestamp add(Timestamp start, Duration length)
      Add a duration to a timestamp.

    • subtract

      public static Timestamp subtract(Timestamp start, Duration length)
      Subtract a duration from a timestamp.