Package com.amazon.ion

Class Timestamp

java.lang.Object
com.amazon.ion.Timestamp
All Implemented Interfaces:
Cloneable, Comparable<Timestamp>
public final class Timestamp extends Object implements Comparable<Timestamp>, 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:

  • Field Details

    • UNKNOWN_OFFSET

      public static final Integer UNKNOWN_OFFSET
      Unknown local offset from UTC.

    • UTC_OFFSET

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

  • Constructor Details

    • 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, 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, 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, BigDecimal frac, 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:
      NullPointerException - if frac is null

    • Timestamp

      @Deprecated public Timestamp(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:

      Throws:
      IllegalArgumentException - if cal has no appropriate calendar fields set.

    • Timestamp

      @Deprecated public Timestamp(BigDecimal millis, 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:
      NullPointerException - if millis is null

    • Timestamp

      @Deprecated public Timestamp(long millis, 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 Details

    • createFromUtcFields

      @Deprecated public static Timestamp createFromUtcFields(Timestamp.Precision p, int zyear, int zmonth, int zday, int zhour, int zminute, int zsecond, BigDecimal frac, 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(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:
      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:

    • 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 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, 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, 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, BigDecimal second, 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, 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(BigDecimal millis, 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:
      NullPointerException - if millis is null

    • forEpochSecond

      public static Timestamp forEpochSecond(long seconds, int nanoOffset, 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(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(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(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 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 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 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 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:

    • getDecimalSecond

      public 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:

    • getFractionalSecond

      @Deprecated public 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:

    • 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:

    • getZDecimalSecond

      public 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:

    • getZFractionalSecond

      @Deprecated public 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:

    • withLocalOffset

      public Timestamp withLocalOffset(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 String toString()
      Returns the string representation (in Ion format) of this Timestamp in its local time.
      Overrides:
      toString in class Object
      See Also:

    • toZString

      public String toZString()
      Returns the string representation (in Ion format) of this Timestamp in UTC.
      See Also:

    • print

      public void print(Appendable out) throws 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:
      IOException - propagated when the Appendable throws it
      See Also:

    • printZ

      public void printZ(Appendable out) throws 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:
      IOException - propagated when the Appendable throws it.
      See Also:

    • 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 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 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:
      NullPointerException - if t is null.
      See Also:

    • equals

      public boolean equals(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 Object
      See Also:

    • 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: