Class Timestamp

  • All Implemented Interfaces:
    java.lang.Comparable<Timestamp>
    Direct Known Subclasses:
    AutoValue_Timestamp

    @Immutable
    public abstract class Timestamp
    extends java.lang.Object
    implements java.lang.Comparable<Timestamp>
    A representation of an instant in time. The instant is the number of nanoseconds after the number of seconds since the Unix Epoch.

    Use Tracing.getClock().now() to get the current timestamp since epoch (1970-01-01T00:00:00Z).

    Since:
    0.5
    • Constructor Summary

      Constructors 
      Constructor Description
      Timestamp()  
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      Timestamp addDuration​(Duration duration)
      Returns a Timestamp calculated as this Timestamp plus some Duration.
      Timestamp addNanos​(long nanosToAdd)
      Returns a Timestamp calculated as this Timestamp plus some number of nanoseconds.
      int compareTo​(Timestamp otherTimestamp)
      Compares this Timestamp to the specified Timestamp.
      static Timestamp create​(long seconds, int nanos)
      Creates a new timestamp from given seconds and nanoseconds.
      private static long floorDiv​(long x, long y)  
      private static long floorMod​(long x, long y)  
      static Timestamp fromMillis​(long epochMilli)
      Creates a new timestamp from the given milliseconds.
      abstract int getNanos()
      Returns the number of nanoseconds after the number of seconds since the Unix Epoch represented by this timestamp.
      abstract long getSeconds()
      Returns the number of seconds since the Unix Epoch represented by this timestamp.
      private static Timestamp ofEpochSecond​(long epochSecond, long nanoAdjustment)  
      private Timestamp plus​(long secondsToAdd, long nanosToAdd)  
      Duration subtractTimestamp​(Timestamp timestamp)
      Returns a Duration calculated as: this - timestamp.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • Timestamp

        Timestamp()
    • Method Detail

      • create

        public static Timestamp create​(long seconds,
                                       int nanos)
        Creates a new timestamp from given seconds and nanoseconds.
        Parameters:
        seconds - Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive.
        nanos - Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive.
        Returns:
        new Timestamp with specified fields.
        Throws:
        java.lang.IllegalArgumentException - if the arguments are out of range.
        Since:
        0.5
      • fromMillis

        public static Timestamp fromMillis​(long epochMilli)
        Creates a new timestamp from the given milliseconds.
        Parameters:
        epochMilli - the timestamp represented in milliseconds since epoch.
        Returns:
        new Timestamp with specified fields.
        Throws:
        java.lang.IllegalArgumentException - if the number of milliseconds is out of the range that can be represented by Timestamp.
        Since:
        0.5
      • getSeconds

        public abstract long getSeconds()
        Returns the number of seconds since the Unix Epoch represented by this timestamp.
        Returns:
        the number of seconds since the Unix Epoch.
        Since:
        0.5
      • getNanos

        public abstract int getNanos()
        Returns the number of nanoseconds after the number of seconds since the Unix Epoch represented by this timestamp.
        Returns:
        the number of nanoseconds after the number of seconds since the Unix Epoch.
        Since:
        0.5
      • addNanos

        public Timestamp addNanos​(long nanosToAdd)
        Returns a Timestamp calculated as this Timestamp plus some number of nanoseconds.
        Parameters:
        nanosToAdd - the nanos to add, positive or negative.
        Returns:
        the calculated Timestamp. For invalid inputs, a Timestamp of zero is returned.
        Throws:
        java.lang.ArithmeticException - if numeric overflow occurs.
        Since:
        0.5
      • addDuration

        public Timestamp addDuration​(Duration duration)
        Returns a Timestamp calculated as this Timestamp plus some Duration.
        Parameters:
        duration - the Duration to add.
        Returns:
        a Timestamp with the specified Duration added.
        Since:
        0.5
      • subtractTimestamp

        public Duration subtractTimestamp​(Timestamp timestamp)
        Returns a Duration calculated as: this - timestamp.
        Parameters:
        timestamp - the Timestamp to subtract.
        Returns:
        the calculated Duration. For invalid inputs, a Duration of zero is returned.
        Since:
        0.5
      • compareTo

        public int compareTo​(Timestamp otherTimestamp)
        Compares this Timestamp to the specified Timestamp.
        Specified by:
        compareTo in interface java.lang.Comparable<Timestamp>
        Parameters:
        otherTimestamp - the other Timestamp to compare to, not null.
        Returns:
        the comparator value: zero if equal, negative if this timestamp happens before otherTimestamp, positive if after.
        Throws:
        java.lang.NullPointerException - if otherTimestamp is null.
      • plus

        private Timestamp plus​(long secondsToAdd,
                               long nanosToAdd)
      • ofEpochSecond

        private static Timestamp ofEpochSecond​(long epochSecond,
                                               long nanoAdjustment)
      • floorDiv

        private static long floorDiv​(long x,
                                     long y)
      • floorMod

        private static long floorMod​(long x,
                                     long y)