Package com.amazon.ion

Class Timestamp

  • All Implemented Interfaces:
    java.lang.Cloneable, java.lang.Comparable<Timestamp>
    public final class Timestamp
extends java.lang.Object
implements java.lang.Comparable<Timestamp>, java.lang.Cloneable
    An immutable representation of a point in time. Ion defines a simple representation of time based on Coordinated Universal Time (UTC). In practice the use of time could be more accurately described as UTC-SLS (UTC Smoothed Leap Seconds) as there is no representation for the leap second discontinuities that UTC has added.

    Timestamps preserve precision, meaning the fields that are included, and the significant digits of any fractional second. Only common break points in the values are supported. Any unspecified fields are handled as the start of the new year/month/day.

    Equality and Comparison

    As with IonValue classes, the equals methods on this class perform a strict equivalence that observes the precision and local offset of each timestamp. This means that it's possible to have two Timestamp instances that represent the same point in time but are not equals.

    On the other hand, the compareTo(com.amazon.ion.Timestamp) methods perform point in time comparison, ignoring precision and local offset. Thus the natural comparison method of this class is not consistent with equals. See the documentation of Comparable for further discussion.

    To illustrate this distinction, consider the following timestamps. None are equals(java.lang.Object) to each other, but any pair will return a zero result from compareTo(com.amazon.ion.Timestamp).

    • 2009T
    • 2009-01T
    • 2009-01-01T
    • 2009-01-01T00:00Z
    • 2009-01-01T00:00:00Z
    • 2009-01-01T00:00:00.0Z
    • 2009-01-01T00:00:00.00Z
    • 2009-01-01T00:00:00.000Z etc.
    See Also:
    equals(Timestamp), compareTo(Timestamp)

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Timestamp.Precision
      The precision of the Timestamp.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.Integer UNKNOWN_OFFSET
      Unknown local offset from UTC.
      static java.lang.Integer UTC_OFFSET
      Local offset of zero hours from UTC.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      Timestamp addDay​(int amount)
      Returns a timestamp relative to this one by the given number of days.
      Timestamp addHour​(int amount)
      Returns a timestamp relative to this one by the given number of hours.
      Timestamp addMillis​(long amount)
      Returns a timestamp relative to this one by the given number of milliseconds.
      Timestamp addMinute​(int amount)
      Returns a timestamp relative to this one by the given number of minutes.
      Timestamp addMonth​(int amount)
      Returns a timestamp relative to this one by the given number of months.
      Timestamp addSecond​(int amount)
      Returns a timestamp relative to this one by the given number of seconds.
      Timestamp addYear​(int amount)
      Returns a timestamp relative to this one by the given number of years.
      Timestamp adjustDay​(int amount)
      Returns a timestamp relative to this one by the given number of days.
      Timestamp adjustHour​(int amount)
      Returns a timestamp relative to this one by the given number of hours.
      Timestamp adjustMillis​(long amount)
      Returns a timestamp relative to this one by the given number of milliseconds.
      Timestamp adjustMinute​(int amount)
      Returns a timestamp relative to this one by the given number of minutes.
      Timestamp adjustMonth​(int amount)
      Returns a timestamp relative to this one by the given number of months.
      Timestamp adjustSecond​(int amount)
      Returns a timestamp relative to this one by the given number of seconds.
      Timestamp adjustYear​(int amount)
      Returns a timestamp relative to this one by the given number of years.
      java.util.Calendar calendarValue()
      Converts the value of this Timestamp as a Calendar, in its local time.
      Timestamp clone()
      Creates a copy of this Timestamp.
      int compareTo​(Timestamp t)
      Performs a comparison of the two points in time represented by two Timestamps.
      static Timestamp createFromUtcFields​(Timestamp.Precision p, int zyear, int zmonth, int zday, int zhour, int zminute, int zsecond, java.math.BigDecimal frac, java.lang.Integer offset)
      Deprecated.
      java.util.Date dateValue()
      Converts the value of this Timestamp into a Date, representing the time in UTC.
      boolean equals​(Timestamp t)
      Compares this Timestamp to another Timestamp object.
      boolean equals​(java.lang.Object t)
      Compares this Timestamp to the specified Object.
      static Timestamp forCalendar​(java.util.Calendar calendar)
      Converts a Calendar to a Timestamp, preserving the calendar's time zone as the equivalent local offset when it has at least minutes precision.
      static Timestamp forDateZ​(java.util.Date date)
      Converts a Date to a Timestamp in UTC representing the same point in time.
      static Timestamp forDay​(int yearZ, int monthZ, int dayZ)
      Returns a Timestamp, precise to the day, with unknown local offset.
      static Timestamp forEpochSecond​(long seconds, int nanoOffset, java.lang.Integer localOffset)
      Returns a Timestamp that represents the point in time that is seconds from the unix epoch (1970-01-01T00:00:00.000Z), with the nanoOffset applied and a given local offset.
      static Timestamp forMillis​(long millis, java.lang.Integer localOffset)
      Returns a Timestamp that represents the point in time that is millis milliseconds from the epoch, with a given local offset.
      static Timestamp forMillis​(java.math.BigDecimal millis, java.lang.Integer localOffset)
      The same as forMillis(long, Integer) but the millisecond component is specified using a BigDecimal and therefore may include fractional milliseconds.
      static Timestamp forMinute​(int year, int month, int day, int hour, int minute, java.lang.Integer offset)
      Returns a Timestamp, precise to the minute, with a given local offset.
      static Timestamp forMonth​(int yearZ, int monthZ)
      Returns a Timestamp, precise to the month, with unknown local offset.
      static Timestamp forSecond​(int year, int month, int day, int hour, int minute, int second, java.lang.Integer offset)
      Returns a Timestamp, precise to the second, with a given local offset.
      static Timestamp forSecond​(int year, int month, int day, int hour, int minute, java.math.BigDecimal second, java.lang.Integer offset)
      Returns a Timestamp, precise to the second, with a given local offset.
      static Timestamp forSqlTimestampZ​(java.sql.Timestamp sqlTimestamp)
      Converts a Timestamp to a Timestamp in UTC representing the same point in time.
      static Timestamp forYear​(int yearZ)
      Returns a Timestamp, precise to the year, with unknown local offset.
      int getDay()
      Returns the day (within the month) of this Timestamp, in its local time.
      java.math.BigDecimal getDecimalMillis()
      Returns a BigDecimal representing the Timestamp's point in time that is the number of milliseconds (including any fractional milliseconds) from the epoch.
      java.math.BigDecimal getDecimalSecond()
      Returns the seconds of this Timestamp.
      java.math.BigDecimal getFractionalSecond()
      Deprecated.
      int getHour()
      Returns the hour of this Timestamp, in its local time.
      java.lang.Integer getLocalOffset()
      Returns the offset of this Timestamp, measured in minutes, for the local timezone in UTC.
      long getMillis()
      Returns a number representing the Timestamp's point in time that is the number of milliseconds (ignoring any fractional milliseconds) from the epoch.
      int getMinute()
      Returns the minute of this Timestamp, in its local time.
      int getMonth()
      Returns the month of this Timestamp, in its local time.
      Timestamp.Precision getPrecision()
      Returns the precision of this Timestamp.
      int getSecond()
      Returns the seconds of this Timestamp, truncated to an integer.
      int getYear()
      Returns the year of this Timestamp, in its local time.
      int getZDay()
      Returns the day of this Timestamp, in UTC.
      java.math.BigDecimal getZDecimalSecond()
      Returns the seconds of this Timestamp.
      java.math.BigDecimal getZFractionalSecond()
      Deprecated.
      Use getZDecimalSecond() instead.
      int getZHour()
      Returns the hour of this Timestamp, in UTC.
      int getZMinute()
      Returns the minute of this Timestamp, in UTC.
      int getZMonth()
      Returns the month of this Timestamp, in UTC.
      int getZSecond()
      Returns the second of this Timestamp.
      int getZYear()
      Returns the year of this Timestamp, in UTC.
      int hashCode()
      Returns a hash code consistent with equals(Object).
      static Timestamp now()
      Returns a Timestamp representing the current time (based on the JVM clock), with an unknown local offset.
      static Timestamp nowZ()
      Returns a Timestamp in UTC representing the current time (based on the the JVM clock).
      void print​(java.lang.Appendable out)
      Prints to an Appendable the string representation (in Ion format) of this Timestamp in its local time.
      void printZ​(java.lang.Appendable out)
      Prints to an Appendable the string representation (in Ion format) of this Timestamp in UTC.
      java.lang.String toString()
      Returns the string representation (in Ion format) of this Timestamp in its local time.
      java.lang.String toZString()
      Returns the string representation (in Ion format) of this Timestamp in UTC.
      static Timestamp valueOf​(java.lang.CharSequence ionFormattedTimestamp)
      Returns a new Timestamp that represents the point in time, precision and local offset defined in Ion format by the CharSequence.
      Timestamp withLocalOffset​(java.lang.Integer offset)
      Returns a timestamp at the same point in time, but with the given local offset.

      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • UNKNOWN_OFFSET

        public static final java.lang.Integer UNKNOWN_OFFSET
        Unknown local offset from UTC.

      • UTC_OFFSET

        public static final java.lang.Integer UTC_OFFSET
        Local offset of zero hours from UTC.

    • Constructor Detail

      • Timestamp

        @Deprecated
public Timestamp​(int zyear,
                 int zmonth,
                 int zday)
        Deprecated.
        Use forDay(int, int, int) instead.
        Creates a new Timestamp, precise to the day, with unknown local offset.

        This is equivalent to the corresponding Ion value YYYY-MM-DD.

      • Timestamp

        @Deprecated
public Timestamp​(int year,
                 int month,
                 int day,
                 int hour,
                 int minute,
                 java.lang.Integer offset)
        Deprecated.
        Use forMinute(int, int, int, int, int, Integer) instead.
        Creates a new Timestamp, precise to the minute, with a given local offset.

        This is equivalent to the corresponding Ion value YYYY-MM-DDThh:mm+-oo:oo, where oo:oo represents the hour and minutes of the local offset from UTC.

        Parameters:
        offset - the local offset from UTC, measured in minutes; may be null to represent an unknown local offset

      • Timestamp

        @Deprecated
public Timestamp​(int year,
                 int month,
                 int day,
                 int hour,
                 int minute,
                 int second,
                 java.lang.Integer offset)
        Deprecated.
        Use forSecond(int, int, int, int, int, int, Integer) instead.
        Creates a new Timestamp, precise to the second, with a given local offset.

        This is equivalent to the corresponding Ion value YYYY-MM-DDThh:mm:ss+-oo:oo, where oo:oo represents the hour and minutes of the local offset from UTC.

        Parameters:
        offset - the local offset from UTC, measured in minutes; may be null to represent an unknown local offset.

      • Timestamp

        @Deprecated
public Timestamp​(int year,
                 int month,
                 int day,
                 int hour,
                 int minute,
                 int second,
                 java.math.BigDecimal frac,
                 java.lang.Integer offset)
        Deprecated.
        Use forSecond(int, int, int, int, int, BigDecimal, Integer) instead.
        Creates a new Timestamp, precise to the second or fractional second, with a given local offset.

        This is equivalent to the corresponding Ion value YYYY-MM-DDThh:mm:ss.fff+-oo:oo, where oo:oo represents the hour and minutes of the local offset from UTC, and fff represents the fractional seconds.

        Parameters:
        frac - the fractional seconds; must not be null; if negative, its absolute value is used
        offset - the local offset from UTC, measured in minutes; may be null to represent an unknown local offset
        Throws:
        java.lang.NullPointerException - if frac is null

      • Timestamp

        @Deprecated
public Timestamp​(java.util.Calendar cal)
        Deprecated.
        Use forCalendar(Calendar) instead.
        Creates a new Timestamp from a Calendar, preserving the Calendar's precision and local offset from UTC.

        The most precise calendar field of cal will be used to determine the precision of the resulting Timestamp. For example, the calendar field will have a Timestamp precision accordingly:

        • Calendar.YEAR - year precision, unknown local offset
        • Calendar.MONTH - month precision, unknown local offset
        • Calendar.DAY_OF_MONTH - day precision, unknown local offset
        • Calendar.HOUR_OF_DAY or Calendar.MINUTE - minute precision
        • Calendar.SECOND - second precision
        • Calendar.MILLISECOND - fractional second precision
        Throws:
        java.lang.IllegalArgumentException - if cal has no appropriate calendar fields set.

      • Timestamp

        @Deprecated
public Timestamp​(java.math.BigDecimal millis,
                 java.lang.Integer localOffset)
        Deprecated.
        Use forMillis(BigDecimal, Integer) instead.
        Creates a new Timestamp that represents the point in time that is millis milliseconds (including any fractional milliseconds) from the epoch, with a given local offset.

        The resulting Timestamp will be precise to the second if millis doesn't contain information that is more granular than seconds. For example, a BigDecimal of value 132541995e4 (132541995 × 104) will return a Timestamp of 2012-01-01T12:12:30Z, precise to the second.

        The resulting Timestamp will be precise to the fractional second if millis contains information that is at least granular to milliseconds. For example, a BigDecimal of value 1325419950555 will return a Timestamp of 2012-01-01T12:12:30.555Z, precise to the fractional second.

        Parameters:
        millis - number of milliseconds (including any fractional milliseconds) from the epoch (1970-01-01T00:00:00.000Z); must not be null
        localOffset - the local offset from UTC, measured in minutes; may be null to represent an unknown local offset
        Throws:
        java.lang.NullPointerException - if millis is null

      • Timestamp

        @Deprecated
public Timestamp​(long millis,
                 java.lang.Integer localOffset)
        Deprecated.
        Use forMillis(long, Integer) instead.
        Creates a new Timestamp that represents the point in time that is millis milliseconds from the epoch, with a given local offset.

        The resulting Timestamp will be precise to the fractional second.

        Parameters:
        millis - number of milliseconds from the epoch (1970-01-01T00:00:00.000Z)
        localOffset - the local offset from UTC, measured in minutes; may be null to represent an unknown local offset.

    • Method Detail

      • createFromUtcFields

        @Deprecated
public static Timestamp createFromUtcFields​(Timestamp.Precision p,
                                            int zyear,
                                            int zmonth,
                                            int zday,
                                            int zhour,
                                            int zminute,
                                            int zsecond,
                                            java.math.BigDecimal frac,
                                            java.lang.Integer offset)
        Deprecated.
        Creates a new Timestamp from the individual time components. The individual time components are expected to be in UTC, with the local offset from UTC (i.e. offset) already applied to the time components. As such, if the given offset is non-null or zero, the resulting Timestamp will have time values that DO NOT match the time parameters. This method also has a behavior of precision "narrowing", detailed in the sub-section below.

        For example, the following method calls will return Timestamps with values (in its local time) respectively: 

         createFromUtcFields(Precision.SECOND, 2012, 2, 3, 4, 5, 6, 0.007, null)    will return 2012-02-03T04:05:06.007-00:00 (match)
 createFromUtcFields(Precision.SECOND, 2012, 2, 3, 4, 5, 6, 0.007, 0)       will return 2012-02-03T04:05:06.007+00:00 (match)
 createFromUtcFields(Precision.SECOND, 2012, 2, 3, 4, 5, 6, 0.007, 480)     will return 2012-02-03T12:05:06.007+08:00 (do not match)
 createFromUtcFields(Precision.SECOND, 2012, 2, 3, 4, 5, 6, 0.007, -480)    will return 2012-02-02T20:05:06.007-08:00 (do not match)
 createFromUtcFields(Precision.SECOND, 2012, 2, 3, 4, 5, 6, 0.007, 720)     will return 2012-02-03T16:05:06.007+12:00 (do not match)
 createFromUtcFields(Precision.SECOND, 2012, 2, 3, 4, 5, 6, 0.007, -720)    will return 2012-02-02T16:05:06.007-12:00 (do not match)
        Note: All of these resulting Timestamps have the similar value (in UTC) 2012-02-03T04:05:06.007Z.

        Precision "Narrowing"

        Any time component that is more precise than the precision parameter p will be excluded from the calculation of the resulting Timestamp's point in time.

        For example, the following method calls will return Timestamps with values respectively: 

         createFromUtcFields(Precision.YEAR    , 2012, 2, 3, 4, 5, 6, 0.007, 0)    will return 2012T
 createFromUtcFields(Precision.MONTH   , 2012, 2, 3, 4, 5, 6, 0.007, 0)    will return 2012-02T
 createFromUtcFields(Precision.DAY     , 2012, 2, 3, 4, 5, 6, 0.007, 0)    will return 2012-02-03T
 createFromUtcFields(Precision.MINUTE  , 2012, 2, 3, 4, 5, 6, 0.007, 0)    will return 2012-02-03T04:05Z
 createFromUtcFields(Precision.SECOND  , 2012, 2, 3, 4, 5, 6,  null, 0)    will return 2012-02-03T04:05:06Z
 createFromUtcFields(Precision.SECOND  , 2012, 2, 3, 4, 5, 6, 0.007, 0)    will return 2012-02-03T04:05:06.007Z
        Parameters:
        p - the desired timestamp precision. The result may have a different precision if the input data isn't precise enough.
        offset - the local offset from UTC, measured in minutes; may be null to represent an unknown local offset.

      • valueOf

        public static Timestamp valueOf​(java.lang.CharSequence ionFormattedTimestamp)
        Returns a new Timestamp that represents the point in time, precision and local offset defined in Ion format by the CharSequence.
        Parameters:
        ionFormattedTimestamp - a sequence of characters that is the Ion representation of a Timestamp
        Returns:
        null if the CharSequence is "null.timestamp"
        Throws:
        java.lang.IllegalArgumentException - if the CharSequence is an invalid Ion representation of a Timestamp; or if the CharSequence has excess characters which are not one of the following valid thirteen numeric-stop characters (escaped accordingly for readability): {}[](),\"\'\ \t\n\r}
        See Also:
        Ion Timestamp Page, W3C Note on Date and Time Formats

      • clone

        public Timestamp clone()
        Creates a copy of this Timestamp. The resulting Timestamp will represent the same point in time and has the same precision and local offset.

        Overrides:
        clone in class java.lang.Object

      • forYear

        public static Timestamp forYear​(int yearZ)
        Returns a Timestamp, precise to the year, with unknown local offset.

        This is equivalent to the corresponding Ion value YYYYT.

      • forMonth

        public static Timestamp forMonth​(int yearZ,
                                 int monthZ)
        Returns a Timestamp, precise to the month, with unknown local offset.

        This is equivalent to the corresponding Ion value YYYY-MMT.

      • forDay

        public static Timestamp forDay​(int yearZ,
                               int monthZ,
                               int dayZ)
        Returns a Timestamp, precise to the day, with unknown local offset.

        This is equivalent to the corresponding Ion value YYYY-MM-DD.

      • forMinute

        public static Timestamp forMinute​(int year,
                                  int month,
                                  int day,
                                  int hour,
                                  int minute,
                                  java.lang.Integer offset)
        Returns a Timestamp, precise to the minute, with a given local offset.

        This is equivalent to the corresponding Ion value YYYY-MM-DDThh:mm+-oo:oo, where oo:oo represents the hour and minutes of the local offset from UTC.

        The values of the year, month, day, hour, and minute parameters are relative to the local offset.

        Parameters:
        offset - the local offset from UTC, measured in minutes; may be null to represent an unknown local offset

      • forSecond

        public static Timestamp forSecond​(int year,
                                  int month,
                                  int day,
                                  int hour,
                                  int minute,
                                  int second,
                                  java.lang.Integer offset)
        Returns a Timestamp, precise to the second, with a given local offset.

        This is equivalent to the corresponding Ion value YYYY-MM-DDThh:mm:ss+-oo:oo, where oo:oo represents the hour and minutes of the local offset from UTC.

        The values of the year, month, day, hour, minute and second parameters are relative to the local offset.

        Parameters:
        offset - the local offset from UTC, measured in minutes; may be null to represent an unknown local offset

      • forSecond

        public static Timestamp forSecond​(int year,
                                  int month,
                                  int day,
                                  int hour,
                                  int minute,
                                  java.math.BigDecimal second,
                                  java.lang.Integer offset)
        Returns a Timestamp, precise to the second, with a given local offset.

        This is equivalent to the corresponding Ion value YYYY-MM-DDThh:mm:ss.sss+-oo:oo, where oo:oo represents the hour and minutes of the local offset from UTC.

        The values of the year, month, day, hour, minute and second parameters are relative to the local offset.

        Parameters:
        second - must be at least zero and less than 60. Must not be null.
        offset - the local offset from UTC, measured in minutes; may be null to represent an unknown local offset

      • forMillis

        public static Timestamp forMillis​(long millis,
                                  java.lang.Integer localOffset)
        Returns a Timestamp that represents the point in time that is millis milliseconds from the epoch, with a given local offset.

        The resulting Timestamp will be precise to the millisecond.

        millis is relative to UTC, regardless of the value supplied for localOffset. This varies from the forMinute(int, int, int, int, int, java.lang.Integer) and forSecond(int, int, int, int, int, int, java.lang.Integer) methods that assume the specified date and time values are relative to the local offset. For example, the following two Timestamps represent the same point in time:

        Timestamp theEpoch = Timestamp.forMillis(0, 0); Timestamp alsoTheEpoch = Timestamp.forSecond(1969, 12, 31, 23, 0, BigDecimal.ZERO, -60);
        Parameters:
        millis - the number of milliseconds from the epoch (1970-01-01T00:00:00.000Z) in UTC.
        localOffset - the local offset from UTC, measured in minutes; may be null to represent an unknown local offset.

      • forMillis

        public static Timestamp forMillis​(java.math.BigDecimal millis,
                                  java.lang.Integer localOffset)
        The same as forMillis(long, Integer) but the millisecond component is specified using a BigDecimal and therefore may include fractional milliseconds.
        Parameters:
        millis - number of milliseconds (including any fractional milliseconds) from the epoch (1970-01-01T00:00:00.000Z); must not be null
        localOffset - the local offset from UTC, measured in minutes; may be null to represent an unknown local offset
        Throws:
        java.lang.NullPointerException - if millis is null

      • forEpochSecond

        public static Timestamp forEpochSecond​(long seconds,
                                       int nanoOffset,
                                       java.lang.Integer localOffset)
        Returns a Timestamp that represents the point in time that is seconds from the unix epoch (1970-01-01T00:00:00.000Z), with the nanoOffset applied and a given local offset.

        This function is intended to allow easy conversion to Timestamp from Java 8's java.time.Instant without having to port this library to Java 8. The following snippet will yield a Timestamp ts that equivalent to the java.time.Instant i:

        Instant i = Instant.now(); Timestamp ts = Timestamp.forEpochSecond(i.getEpochSecond(), i.getNano(), 0);

        Like forMillis(long, java.lang.Integer), seconds is relative to UTC, regardless of the value supplied for localOffset.

        Parameters:
        seconds - The number of seconds from the unix epoch (1970-01-01T00:00:00.000Z) UTC.
        nanoOffset - The number of nanoseconds for the fractional component. Must be between 0 and 999,999,999.
        localOffset - the local offset from UTC, measured in minutes; may be null to represent an unknown local offset.

      • forCalendar

        public static Timestamp forCalendar​(java.util.Calendar calendar)
        Converts a Calendar to a Timestamp, preserving the calendar's time zone as the equivalent local offset when it has at least minutes precision.
        Returns:
        a Timestamp instance, with precision determined by the smallest field set in the Calendar; or null if calendar is null

      • forDateZ

        public static Timestamp forDateZ​(java.util.Date date)
        Converts a Date to a Timestamp in UTC representing the same point in time.

        The resulting Timestamp will be precise to the millisecond.

        Returns:
        a new Timestamp instance, in UTC, precise to the millisecond; null if date is null

      • forSqlTimestampZ

        public static Timestamp forSqlTimestampZ​(java.sql.Timestamp sqlTimestamp)
        Converts a Timestamp to a Timestamp in UTC representing the same point in time.

        The resulting Timestamp will be precise to the nanosecond.

        Parameters:
        sqlTimestamp - assumed to have nanoseconds precision
        Returns:
        a new Timestamp instance, in UTC, precise to the nanosecond null if sqlTimestamp is null

      • now

        public static Timestamp now()
        Returns a Timestamp representing the current time (based on the JVM clock), with an unknown local offset.

        The resulting Timestamp will be precise to the millisecond.

        Returns:
        a new Timestamp instance representing the current time.

      • nowZ

        public static Timestamp nowZ()
        Returns a Timestamp in UTC representing the current time (based on the the JVM clock).

        The resulting Timestamp will be precise to the millisecond.

        Returns:
        a new Timestamp instance, in UTC, representing the current time.

      • dateValue

        public java.util.Date dateValue()
        Converts the value of this Timestamp into a Date, representing the time in UTC.

        This method will return the same result for all Timestamps representing the same point in time, regardless of the local offset.

        Because Date instances are mutable, this method returns a new instance from each call.

        Returns:
        a new Date instance, in UTC

      • calendarValue

        public java.util.Calendar calendarValue()
        Converts the value of this Timestamp as a Calendar, in its local time.

        Because Calendar instances are mutable, this method returns a new instance from each call.

        Returns:
        a new Calendar instance, in its local time.

      • getMillis

        public long getMillis()
        Returns a number representing the Timestamp's point in time that is the number of milliseconds (ignoring any fractional milliseconds) from the epoch.

        This method will return the same result for all Timestamps representing the same point in time, regardless of the local offset.

        Returns:
        number of milliseconds (ignoring any fractional milliseconds) from the epoch (1970-01-01T00:00:00.000Z)

      • getDecimalMillis

        public java.math.BigDecimal getDecimalMillis()
        Returns a BigDecimal representing the Timestamp's point in time that is the number of milliseconds (including any fractional milliseconds) from the epoch.

        This method will return the same result for all Timestamps representing the same point in time, regardless of the local offset.

        Returns:
        number of milliseconds (including any fractional milliseconds) from the epoch (1970-01-01T00:00:00.000Z)

      • getPrecision

        public Timestamp.Precision getPrecision()
        Returns the precision of this Timestamp.

      • getLocalOffset

        public java.lang.Integer getLocalOffset()
        Returns the offset of this Timestamp, measured in minutes, for the local timezone in UTC.

        For example, calling this method on Timestamps of:

        • 1969-02-23T07:00+07:00 will return 420
        • 1969-02-22T22:45:00.00-01:15 will return -75
        • 1969-02-23 (by Ion's definition, equivalent to 1969-02-23T00:00-00:00) will return null
        Returns:
        null if the local offset is unknown (i.e. -00:00)

      • getYear

        public int getYear()
        Returns the year of this Timestamp, in its local time.
        Returns:
        a number within the range [1, 9999], in its local time

      • getMonth

        public int getMonth()
        Returns the month of this Timestamp, in its local time.
        Returns:
        a number within the range [1, 12], whereby 1 refers to January and 12 refers to December, in its local time; 1 is returned if the Timestamp isn't precise to the month

      • getDay

        public int getDay()
        Returns the day (within the month) of this Timestamp, in its local time.
        Returns:
        a number within the range [1, 31], in its local time; 1 is returned if the Timestamp isn't precise to the day

      • getHour

        public int getHour()
        Returns the hour of this Timestamp, in its local time.
        Returns:
        a number within the range [0, 23], in its local time; 0 is returned if the Timestamp isn't precise to the hour

      • getMinute

        public int getMinute()
        Returns the minute of this Timestamp, in its local time.
        Returns:
        a number within the range [0, 59], in its local time; 0 is returned if the Timestamp isn't precise to the minute

      • getSecond

        public int getSecond()
        Returns the seconds of this Timestamp, truncated to an integer.

        Seconds are not affected by local offsets. As such, this method produces the same output as getZSecond().

        Returns:
        a number within the range [0, 59]; 0 is returned if the Timestamp isn't precise to the second
        See Also:
        getZSecond()

      • getDecimalSecond

        public java.math.BigDecimal getDecimalSecond()
        Returns the seconds of this Timestamp.

        Seconds are not affected by local offsets. As such, this method produces the same output as getZDecimalSecond().

        Returns:
        a number within the range [0, 60); 0 is returned if the Timestamp isn't precise to the second
        See Also:
        getZDecimalSecond()

      • getFractionalSecond

        @Deprecated
public java.math.BigDecimal getFractionalSecond()
        Deprecated.
        Returns the fractional second of this Timestamp.

        Fractional seconds are not affected by local offsets. As such, this method produces the same output as getZFractionalSecond().

        Returns:
        a BigDecimal within the range [0, 1); null is returned if the Timestamp isn't precise to the fractional second
        See Also:
        Use instead.

      • getZYear

        public int getZYear()
        Returns the year of this Timestamp, in UTC.
        Returns:
        a number within the range [1, 9999], in UTC

      • getZMonth

        public int getZMonth()
        Returns the month of this Timestamp, in UTC.
        Returns:
        a number within the range [1, 12], whereby 1 refers to January and 12 refers to December, in UTC; 1 is returned if the Timestamp isn't precise to the month

      • getZDay

        public int getZDay()
        Returns the day of this Timestamp, in UTC.
        Returns:
        a number within the range [1, 31], in UTC; 1 is returned if the Timestamp isn't precise to the day

      • getZHour

        public int getZHour()
        Returns the hour of this Timestamp, in UTC.
        Returns:
        a number within the range [0, 23], in UTC; 0 is returned if the Timestamp isn't precise to the hour

      • getZMinute

        public int getZMinute()
        Returns the minute of this Timestamp, in UTC.
        Returns:
        a number within the range [0, 59], in UTC; 0 is returned if the Timestamp isn't precise to the minute

      • getZSecond

        public int getZSecond()
        Returns the second of this Timestamp.

        Seconds are not affected by local offsets. As such, this method produces the same output as getSecond().

        Returns:
        a number within the range [0, 59]; 0 is returned if the Timestamp isn't precise to the second
        See Also:
        getSecond()

      • getZDecimalSecond

        public java.math.BigDecimal getZDecimalSecond()
        Returns the seconds of this Timestamp.

        Seconds are not affected by local offsets. As such, this method produces the same output as getDecimalSecond().

        Returns:
        a number within the range [0, 60); 0 is returned if the Timestamp isn't precise to the second
        See Also:
        getDecimalSecond()

      • getZFractionalSecond

        @Deprecated
public java.math.BigDecimal getZFractionalSecond()
        Deprecated.
        Use getZDecimalSecond() instead.
        Returns the fractional second of this Timestamp.

        Fractional seconds are not affected by local offsets. As such, this method produces the same output as getFractionalSecond().

        Returns:
        a BigDecimal within the range [0, 1); null is returned if the Timestamp isn't precise to the fractional second
        See Also:
        getFractionalSecond()

      • withLocalOffset

        public Timestamp withLocalOffset​(java.lang.Integer offset)
        Returns a timestamp at the same point in time, but with the given local offset. If this timestamp has precision coarser than minutes, then it is returned unchanged since such timestamps always have an unknown offset.

      • toString

        public java.lang.String toString()
        Returns the string representation (in Ion format) of this Timestamp in its local time.
        Overrides:
        toString in class java.lang.Object
        See Also:
        toZString(), print(Appendable)

      • toZString

        public java.lang.String toZString()
        Returns the string representation (in Ion format) of this Timestamp in UTC.
        See Also:
        toString(), printZ(Appendable)

      • print

        public void print​(java.lang.Appendable out)
           throws java.io.IOException
        Prints to an Appendable the string representation (in Ion format) of this Timestamp in its local time.

        This method produces the same output as toString().

        Parameters:
        out - not null
        Throws:
        java.io.IOException - propagated when the Appendable throws it
        See Also:
        printZ(Appendable)

      • printZ

        public void printZ​(java.lang.Appendable out)
            throws java.io.IOException
        Prints to an Appendable the string representation (in Ion format) of this Timestamp in UTC.

        This method produces the same output as toZString().

        Parameters:
        out - not null
        Throws:
        java.io.IOException - propagated when the Appendable throws it.
        See Also:
        print(Appendable)

      • adjustMillis

        public final Timestamp adjustMillis​(long amount)
        Returns a timestamp relative to this one by the given number of milliseconds.

        This method always returns a Timestamp with the same precision as the original. After performing the arithmetic, the resulting Timestamp's seconds value will be truncated to the same fractional precision as the original. For example, adjusting 2012-04-01T00:00:00Z by one millisecond results in 2012-04-01T00:00:00Z; adjusting 2012-04-01T00:00:00.0010Z by -1 millisecond results in 2012-04-01T00:00:00.0000Z. To extend the precision when the original Timestamp has coarser than SECOND precision and to avoid truncation of the seconds value, use addSecond(int).

        Parameters:
        amount - a number of milliseconds.

      • addMillis

        public final Timestamp addMillis​(long amount)
        Returns a timestamp relative to this one by the given number of milliseconds.

        This method always returns a Timestamp with SECOND precision and a seconds value precise at least to the millisecond. For example, adding one millisecond to 2011T results in 2011-01-01T00:00:00.001-00:00. To receive a Timestamp that always maintains the same precision as the original, use adjustMillis(long). milliseconds.

        Parameters:
        amount - a number of milliseconds.

      • adjustSecond

        public final Timestamp adjustSecond​(int amount)
        Returns a timestamp relative to this one by the given number of seconds.

        This method always returns a Timestamp with the same precision as the original. For example, adjusting 2012-04-01T00:00Z by one second results in 2012-04-01T00:00Z; adjusting 2012-04-01T00:00:00Z by -1 second results in 2012-03-31T23:59:59Z. To extend the precision when the original Timestamp has coarser than SECOND precision, use addSecond(int).

        Parameters:
        amount - a number of seconds.

      • addSecond

        public final Timestamp addSecond​(int amount)
        Returns a timestamp relative to this one by the given number of seconds.

        This method always returns a Timestamp with SECOND precision. For example, adding one second to 2011T results in 2011-01-01T00:00:01-00:00. To receive a Timestamp that always maintains the same precision as the original, use adjustSecond(int).

        Parameters:
        amount - a number of seconds.

      • adjustMinute

        public final Timestamp adjustMinute​(int amount)
        Returns a timestamp relative to this one by the given number of minutes.

        This method always returns a Timestamp with the same precision as the original. For example, adjusting 2012-04-01T by one minute results in 2012-04-01T; adjusting 2012-04-01T00:00-00:00 by -1 minute results in 2012-03-31T23:59-00:00. To extend the precision when the original Timestamp has coarser than MINUTE precision, use addMinute(int).

        Parameters:
        amount - a number of minutes.

      • addMinute

        public final Timestamp addMinute​(int amount)
        Returns a timestamp relative to this one by the given number of minutes.

        This method always returns a Timestamp with at least MINUTE precision. For example, adding one minute to 2011T results in 2011-01-01T00:01-00:00. To receive a Timestamp that always maintains the same precision as the original, use adjustMinute(int).

        Parameters:
        amount - a number of minutes.

      • adjustHour

        public final Timestamp adjustHour​(int amount)
        Returns a timestamp relative to this one by the given number of hours.

        This method always returns a Timestamp with the same precision as the original. For example, adjusting 2012-04-01T by one hour results in 2012-04-01T; adjusting 2012-04-01T00:00-00:00 by -1 hour results in 2012-03-31T23:00-00:00. To extend the precision when the original Timestamp has coarser than MINUTE precision, use addHour(int).

        Parameters:
        amount - a number of hours.

      • addHour

        public final Timestamp addHour​(int amount)
        Returns a timestamp relative to this one by the given number of hours.

        This method always returns a Timestamp with at least MINUTE precision. For example, adding one hour to 2011T results in 2011-01-01T01:00-00:00. To receive a Timestamp that always maintains the same precision as the original, use adjustHour(int).

        Parameters:
        amount - a number of hours.

      • adjustDay

        public final Timestamp adjustDay​(int amount)
        Returns a timestamp relative to this one by the given number of days.

        This method always returns a Timestamp with the same precision as the original. For example, adjusting 2012-04T by one day results in 2012-04T; adjusting 2012-04-01T by -1 days results in 2012-03-31T. To extend the precision when the original Timestamp has coarser than DAY precision, use addDay(int).

        Parameters:
        amount - a number of days.

      • addDay

        public final Timestamp addDay​(int amount)
        Returns a timestamp relative to this one by the given number of days.
        Parameters:
        amount - a number of days.

      • adjustMonth

        public final Timestamp adjustMonth​(int amount)
        Returns a timestamp relative to this one by the given number of months. The day field may be adjusted to account for different month length and leap days.

        This method always returns a Timestamp with the same precision as the original. For example, adjusting 2011T by one month results in 2011T; adding 12 months to 2011T results in 2012T. To extend the precision when the original Timestamp has coarser than MONTH precision, use addMonth(int).

        Parameters:
        amount - a number of months.

      • addMonth

        public final Timestamp addMonth​(int amount)
        Returns a timestamp relative to this one by the given number of months. The day field may be adjusted to account for different month length and leap days. For example, adding one month to 2011-01-31 results in 2011-02-28.
        Parameters:
        amount - a number of months.

      • adjustYear

        public final Timestamp adjustYear​(int amount)
        Returns a timestamp relative to this one by the given number of years. The day field may be adjusted to account for leap days. For example, adjusting 2012-02-29 by one year results in 2013-02-28.

        Because YEAR is the coarsest precision possible, this method always returns a Timestamp with the same precision as the original and behaves identically to addYear(int).

        Parameters:
        amount - a number of years.

      • addYear

        public final Timestamp addYear​(int amount)
        Returns a timestamp relative to this one by the given number of years. The day field may be adjusted to account for leap days. For example, adding one year to 2012-02-29 results in 2013-02-28.
        Parameters:
        amount - a number of years.

      • hashCode

        public int hashCode()
        Returns a hash code consistent with equals(Object).

        Overrides:
        hashCode in class java.lang.Object

      • compareTo

        public int compareTo​(Timestamp t)
        Performs a comparison of the two points in time represented by two Timestamps. If the point in time represented by this Timestamp precedes that of t, then -1 is returned. If t precedes this Timestamp then 1 is returned. If the Timestamps represent the same point in time, then 0 is returned. Note that a 0 result does not imply that the two Timestamps are equals(java.lang.Object), as the local offset or precision of the two Timestamps may be different.

        This method is provided in preference to individual methods for each of the six boolean comparison operators (<, ==, >, >=, !=, <=). The suggested idiom for performing these comparisons is: (x.compareTo(y)<op>0), where <op> is one of the six comparison operators.

        For example, the pairs below will return a 0 result:

        • 2009T
        • 2009-01T
        • 2009-01-01T
        • 2009-01-01T00:00Z
        • 2009-01-01T00:00:00Z
        • 2009-01-01T00:00:00.0Z
        • 2009-01-01T00:00:00.00Z
        • 2008-12-31T16:00-08:00
        • 2008-12-31T12:00-12:00
        • 2009-01-01T12:00+12:00

        Use the equals(Timestamp) method to compare the point in time, including precision and local offset.

        Specified by:
        compareTo in interface java.lang.Comparable<Timestamp>
        Parameters:
        t - the other Timestamp to compare this Timestamp to
        Returns:
        -1, 0, or 1 if this Timestamp is less than, equal to, or greater than t respectively
        Throws:
        java.lang.NullPointerException - if t is null.
        See Also:
        equals(Timestamp)

      • equals

        public boolean equals​(java.lang.Object t)
        Compares this Timestamp to the specified Object. The result is true if and only if the parameter is a Timestamp object that represents the same point in time, precision and local offset as this Timestamp.

        Use the compareTo(Timestamp) method to compare only the point in time, ignoring precision and local offset.

        Overrides:
        equals in class java.lang.Object
        See Also:
        equals(Timestamp), compareTo(Timestamp)

      • equals

        public boolean equals​(Timestamp t)
        Compares this Timestamp to another Timestamp object. The result is true if and only if the parameter represents the same point in time and has the same precision and local offset as this object.

        These pairs are equals(java.lang.Object) to each other, as they represent the same points in time, precision and local offset:

        • 2001-01-01T11:22+00:00 (minute precision, in UTC)
        • 2001-01-01T11:22Z (minute precision, in UTC)

        On the other hand, none of these pairs are equals(java.lang.Object) to each other, they represent the same points in time, but with different precisions and/or local offsets:

        • 2001T (year precision, unknown local offset)
        • 2001-01T (month precision, unknown local offset)
        • 2001-01-01T (day precision, unknown local offset)
        • 2001-01-01T00:00-00:00 (second precision, unknown local offset)
        • 2001-01-01T00:00+00:00 (second precision, in UTC)
        • 2001-01-01T00:00.000-00:00 (millisecond precision, unknown local offset)
        • 2001-01-01T00:00.000+00:00 (millisecond precision, in UTC)

        Use the compareTo(Timestamp) method to compare only the point in time, ignoring precision and local offset.

        See Also:
        compareTo(Timestamp)