Package com.google.protobuf.util

Class Timestamps

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

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static com.google.protobuf.Timestamp EPOCH
      A constant holding the Timestamp of epoch time, 1970-01-01T00:00:00.000000000Z.
      static com.google.protobuf.Timestamp MAX_VALUE
      A constant holding the maximum valid Timestamp, 9999-12-31T23:59:59.999999999Z.
      static com.google.protobuf.Timestamp MIN_VALUE
      A constant holding the minimum valid Timestamp, 0001-01-01T00:00:00Z.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static com.google.protobuf.Timestamp add​(com.google.protobuf.Timestamp start, com.google.protobuf.Duration length)
      Add a duration to a timestamp.
      static com.google.protobuf.Duration between​(com.google.protobuf.Timestamp from, com.google.protobuf.Timestamp to)
      Calculate the difference between two timestamps.
      static com.google.protobuf.Timestamp checkValid​(com.google.protobuf.Timestamp timestamp)
      Throws an IllegalArgumentException if the given Timestamp is not valid.
      static com.google.protobuf.Timestamp checkValid​(com.google.protobuf.Timestamp.Builder timestampBuilder)
      Builds the given builder and throws an IllegalArgumentException if it is not valid.
      static java.util.Comparator<com.google.protobuf.Timestamp> comparator()
      Returns a Comparator for Timestamps which sorts in increasing chronological order.
      static int compare​(com.google.protobuf.Timestamp x, com.google.protobuf.Timestamp y)
      Compares two timestamps.
      static com.google.protobuf.Timestamp fromMicros​(long microseconds)
      Create a Timestamp from the number of microseconds elapsed from the epoch.
      static com.google.protobuf.Timestamp fromMillis​(long milliseconds)
      Create a Timestamp from the number of milliseconds elapsed from the epoch.
      static com.google.protobuf.Timestamp fromNanos​(long nanoseconds)
      Create a Timestamp from the number of nanoseconds elapsed from the epoch.
      static com.google.protobuf.Timestamp fromSeconds​(long seconds)
      Create a Timestamp from the number of seconds elapsed from the epoch.
      static boolean isValid​(long seconds, int nanos)
      Returns true if the given number of seconds and nanos is a valid Timestamp.
      static boolean isValid​(com.google.protobuf.Timestamp timestamp)
      Returns true if the given Timestamp is valid.
      static com.google.protobuf.Timestamp parse​(java.lang.String value)
      Parse from RFC 3339 date string to Timestamp.
      static com.google.protobuf.Timestamp subtract​(com.google.protobuf.Timestamp start, com.google.protobuf.Duration length)
      Subtract a duration from a timestamp.
      static long toMicros​(com.google.protobuf.Timestamp timestamp)
      Convert a Timestamp to the number of microseconds elapsed from the epoch.
      static long toMillis​(com.google.protobuf.Timestamp timestamp)
      Convert a Timestamp to the number of milliseconds elapsed from the epoch.
      static long toNanos​(com.google.protobuf.Timestamp timestamp)
      Convert a Timestamp to the number of nanoseconds elapsed from the epoch.
      static long toSeconds​(com.google.protobuf.Timestamp timestamp)
      Convert a Timestamp to the number of seconds elapsed from the epoch.
      static java.lang.String toString​(com.google.protobuf.Timestamp timestamp)
      Convert Timestamp to RFC 3339 date string format.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • MIN_VALUE

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

      • MAX_VALUE

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

      • EPOCH

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

    • Method Detail

      • comparator

        public static java.util.Comparator<com.google.protobuf.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)).

      • compare

        public static int compare​(com.google.protobuf.Timestamp x,
                          com.google.protobuf.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​(com.google.protobuf.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 com.google.protobuf.Timestamp checkValid​(com.google.protobuf.Timestamp timestamp)
        Throws an IllegalArgumentException if the given Timestamp is not valid.

      • checkValid

        public static com.google.protobuf.Timestamp checkValid​(com.google.protobuf.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 java.lang.String toString​(com.google.protobuf.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"

        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 com.google.protobuf.Timestamp parse​(java.lang.String value)
                                           throws java.text.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:
        java.text.ParseException - if parsing fails.

      • fromSeconds

        public static com.google.protobuf.Timestamp fromSeconds​(long seconds)
        Create a Timestamp from the number of seconds elapsed from the epoch.

      • toSeconds

        public static long toSeconds​(com.google.protobuf.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 com.google.protobuf.Timestamp fromMillis​(long milliseconds)
        Create a Timestamp from the number of milliseconds elapsed from the epoch.

      • toMillis

        public static long toMillis​(com.google.protobuf.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.

      • fromMicros

        public static com.google.protobuf.Timestamp fromMicros​(long microseconds)
        Create a Timestamp from the number of microseconds elapsed from the epoch.

      • toMicros

        public static long toMicros​(com.google.protobuf.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 com.google.protobuf.Timestamp fromNanos​(long nanoseconds)
        Create a Timestamp from the number of nanoseconds elapsed from the epoch.

      • toNanos

        public static long toNanos​(com.google.protobuf.Timestamp timestamp)
        Convert a Timestamp to the number of nanoseconds elapsed from the epoch.

      • between

        public static com.google.protobuf.Duration between​(com.google.protobuf.Timestamp from,
                                                   com.google.protobuf.Timestamp to)
        Calculate the difference between two timestamps.

      • add

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

      • subtract

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