Package net.time4j

Class Moment

java.lang.Object
net.time4j.engine.ChronoEntity<T>
net.time4j.engine.TimePoint<TimeUnit,​Moment>
net.time4j.Moment
All Implemented Interfaces:
Serializable, Comparable<Moment>, TemporalAccessor, UnixTime, ChronoDisplay, Temporal<UniversalTime>, ThreetenAdapter, UniversalTime
@CalendarType("iso8601") public final class Moment extends TimePoint<TimeUnit,​Moment> implements UniversalTime, Temporal<UniversalTime>, ThreetenAdapter

Represents an instant/moment on the universal timeline with reference to the timezone UTC (UTC+00:00 / Greenwich-meridian).

The JDK-equivalent is traditionally the class java.util.Date. In contrast to that old class this class stores the elapsed time not just in millisecond but in nanosecond precision on 96-bit base.

Following elements which are declared as constants are registered by this class with access in UTC timezone:

Furthermore, most local elements like PlainTime.ISO_HOUR etc. registered in class PlainTimestamp or those defined in Weekmodel are indirectly supported via the queries in the interface ZonalElement. A Moment is also capable of delivering the date- and time-values in a different timezone if the method toZonalTimestamp(TZID) is called. If zonal operators are defined by any elements then manipulations of related data are possible in any timezone.

Time arithmetic

The main time units are defined by SI (counting possible UTC-leapseconds) and TimeUnit. Latter unit type can be used if a better interoperability is needed for external APIs which ignore leapseconds. Both kinds of time units can be used in the methods plus(long, unit), minus(long, unit) and until(Moment, unit).

Time scales

Following table illustrates how a time scale affects values and representations before, during and after a leap second event. Two views exist, either interpreting a moment as count of seconds elapsed since an epoch (value space) or printed in a lexical representation. In latter case, a combination of a ChronoFormatter with the format attribute Attributes.TIME_SCALE can achieve a more flexible lexical representation.

Scale-specific epoch => Moment.of(0, scale)
time scale value space
getElapsedTime(scale)
getNanosecond(scale)		 lexical space
toString(scale)		 in UT/UTC
toString()
POSIX 0.000 POSIX-1970-01-01T00Z 1970-01-01T00:00:00Z
UTC 0.000 UTC-1972-01-01T00Z 1972-01-01T00:00:00Z
TAI 0.000 TAI-1958-01-01T00Z TAI-1957-12-31T23:59:59,658300736Z *)
GPS 0.000 GPS-1980-01-06T00Z 1980-01-06T00:00:00Z
TT 0.000 TT-1972-01-01T00Z 1971-12-31T23:59:17,716215710Z *)
UT 0.000 UT-1972-01-01T00Z 1972-01-01T00:00:00,102604456Z *)

*) Approximation based on the calculation of delta-T.

What does happen around a leap second (at the end of 2016)?
time scale value space
getElapsedTime(scale)
getNanosecond(scale)		 lexical space
toString(scale)
POSIX 1483228799.000
1483228799.000
1483228800.000		 2016-12-31T23:59:59.000Z
2016-12-31T23:59:59.000Z
2017-01-01T00:00:00.000Z
UTC 1420156825.000
1420156826.000
1420156827.000		 2016-12-31T23:59:59.000Z
2016-12-31T23:59:60.000Z
2017-01-01T00:00:00.000Z
TAI 1861920035.000
1861920036.000
1861920037.000		 2017-01-01T00:00:35.000Z
2017-01-01T00:00:36.000Z
2017-01-01T00:00:37.000Z
GPS 1167264016.000
1167264017.000
1167264018.000		 2017-01-01T00:00:16.000Z
2017-01-01T00:00:17.000Z
2017-01-01T00:00:18.000Z
TT 1420156867.184
1420156868.184
1420156869.184		 2017-01-01T00:01:07,184Z
2017-01-01T00:01:08,184Z
2017-01-01T00:01:09,184Z
UT 1420156798.600
1420156799.600
1420156800.599		 2016-12-31T23:59:58,600Z
2016-12-31T23:59:59,600Z
2017-01-01T00:00:00,599Z
Author:
Meno Hochschild
See Also:
Serialized Form

  • Field Details

    • UNIX_EPOCH

      public static final Moment UNIX_EPOCH

      Start of UNIX-era = [1970-01-01T00:00:00,000000000Z].

    • POSIX_TIME

      public static final ChronoElement<Long> POSIX_TIME

      Represents the POSIX-time in seconds since UNIX-epoch.

      Since:
      2.0

    • FRACTION

      public static final ChronoElement<Integer> FRACTION

      Represents the nano-fraction of current second.

      Since:
      2.0

    • PRECISION

      public static final ChronoElement<TimeUnit> PRECISION

      Represents the precision.

      Since:
      3.7/4.5

  • Method Details

    • of

      public static Moment of​(long elapsedTime, TimeScale scale)

      Equivalent to Moment.of(elapsedTime, 0, scale).

      Parameters:
      elapsedTime - elapsed seconds on given time scale
      scale - time scale reference
      Returns:
      new moment instance
      Throws:
      IllegalArgumentException - if elapsed time is out of range limits beyond year +/-999,999,999 or out of time scale range
      IllegalStateException - if time scale is not POSIX but leap second support is switched off by configuration
      See Also:
      LeapSeconds.isEnabled()

    • of

      public static Moment of​(long elapsedTime, int nanosecond, TimeScale scale)

      Creates a new UTC-timestamp by given time coordinates on given time scale.

      The given elapsed time elapsedTime will be internally transformed into the UTC-epochtime, should another time scale than UTC be given. The time scale TAI will only be supported earliest on TAI start 1958-01-01, the time scale GPS earliest on 1980-01-06.

      Parameters:
      elapsedTime - elapsed seconds on given time scale
      nanosecond - nanosecond fraction of last second
      scale - time scale reference
      Returns:
      new moment instance
      Throws:
      IllegalArgumentException - if the nanosecond is not in the range 0 <= nanosecond <= 999,999,999 or if elapsed time is out of supported range limits beyond year +/-999,999,999 or out of time scale range
      IllegalStateException - if time scale is not POSIX but leap second support is switched off by configuration
      See Also:
      LeapSeconds.isEnabled()

    • nowInSystemTime

      public static Moment nowInSystemTime()

      Obtains the current time using the system clock.

      Equivalent alternative for: SystemClock.currentMoment().

      Returns:
      current moment using the system clock
      Since:
      3.23/4.19
      See Also:
      SystemClock.currentMoment()

    • from

      public static Moment from​(UnixTime ut)

      Common conversion method.

      Parameters:
      ut - UNIX-timestamp
      Returns:
      corresponding Moment

    • from

      public static Moment from​(Instant instant)

      Short cut for TemporalType.INSTANT.translate(instant).

      Parameters:
      instant - Threeten-equivalent of this instance
      Returns:
      Moment
      Since:
      4.0
      See Also:
      TemporalType.INSTANT

    • getPosixTime

      public long getPosixTime()
      Description copied from interface: UnixTime

      Counts the seconds elapsed since UNIX epoch [1970-01-01T00:00:00Z] in UTC timezone.

      Specified by:
      getPosixTime in interface UnixTime
      Returns:
      count of seconds since UNIX-epoch at [1970-01-01T00:00:00Z] without leap seconds in the timezone UTC (Greenwich)

    • getElapsedTime

      public long getElapsedTime​(TimeScale scale)
      Description copied from interface: UniversalTime

      Represents this timestamp as elpased seconds on given time scale.

      The method getPosixTime() inherited from UnixTime is equivalent to getElapsedTime(TimeScale.POSIX) and relates to the UNIX-epoch 1970-01-01. The time scale UTC starts two years later however and also counts leapseconds.

      Specified by:
      getElapsedTime in interface UniversalTime
      Parameters:
      scale - time scale reference
      Returns:
      elapsed seconds in given time scale

    • getNanosecond

      public int getNanosecond()
      Description copied from interface: UnixTime

      Yields the nanosecond fraction of current second.

      As time unit, the nanosecond is defined as one billionth part of a second).

      Specified by:
      getNanosecond in interface UnixTime
      Returns:
      count of nanoseconds as fraction of last second in the range 0 - 999.999.999

    • getNanosecond

      public int getNanosecond​(TimeScale scale)
      Description copied from interface: UniversalTime

      Represents the nanosecond part on the given time scale.

      The method with the same name and without argument inherited from super interface UnixTime is identical to this method if the time scale is either POSIX or UTC.

      Specified by:
      getNanosecond in interface UniversalTime
      Parameters:
      scale - time scale reference
      Returns:
      nanosecond fraction in given time scale

    • isLeapSecond

      public boolean isLeapSecond()
      Description copied from interface: UniversalTime

      Queries if this time point is within a positive leapsecond.

      If the support for UTC-leapseconds is switched off per configuration then this method will always yield false.

      Specified by:
      isLeapSecond in interface UniversalTime
      Returns:
      true if this instance represents a positive leap second else false
      See Also:
      LeapSeconds.isEnabled()

    • nextLeapSecond

      public static ChronoOperator<Moment> nextLeapSecond()

      Tries to determine the next coming leap second.

      Returns:
      operator which either gets next leap second or null if unknown or disabled
      Since:
      2.1

    • transform

      public BigDecimal transform​(TimeScale scale)

      Represents this timestamp as decimal value in given time scale.

      The scale determines the epoch reference to be used and how to count elapsed seconds since a given epoch. Please note that some scales like TAI, GPS and UTC are atomic scales counting SI-seconds continuously. Such time scales do not suppress leap seconds in this view. However, the scales handle the representation of leap seconds in a very different way. TAI for example does not consider leap seconds as leap seconds but just normal seconds (in the model of 1 TAI-day = 86400 SI-seconds) while UTC lables leap seconds with the special value 60 causing discontinuities.

      Parameters:
      scale - time scale reference
      Returns:
      decimal value in given time scale as seconds inclusive fraction
      Throws:
      IllegalArgumentException - if this instance is out of range for given time scale
      See Also:
      toString(TimeScale)

    • isAfter

      public boolean isAfter​(UniversalTime temporal)
      Description copied from interface: Temporal

      Queries if this object is after given object on a timeline.

      Specified by:
      isAfter in interface Temporal<UniversalTime>
      Parameters:
      temporal - object this instance is compared to
      Returns:
      true if this instance is temporally after temporal else false

    • isBefore

      public boolean isBefore​(UniversalTime temporal)
      Description copied from interface: Temporal

      Queries if this object is before given object on a timeline.

      Specified by:
      isBefore in interface Temporal<UniversalTime>
      Parameters:
      temporal - object this instance is compared to
      Returns:
      true if this instance is temporally before temporal else false

    • isSimultaneous

      public boolean isSimultaneous​(UniversalTime temporal)
      Description copied from interface: Temporal

      Queries if this object and given object have the same position on the time axis.

      Is equivalent to !isAfter(temporal) && !isBefore(temporal). This method differs from the Object-method equals() such that first the comparison type must be a temporal one and second that only temporal-only state will be considered.

      Specified by:
      isSimultaneous in interface Temporal<UniversalTime>
      Parameters:
      temporal - object this instance is compared to
      Returns:
      true if this instance is temporally equal to temporal else false

    • toLocalTimestamp

      public PlainTimestamp toLocalTimestamp()

      Converts this instance to a local timestamp in the system timezone.

      Returns:
      local timestamp in system timezone (leap seconds will always be lost)
      Since:
      1.2
      See Also:
      Timezone.ofSystem(), toZonalTimestamp(TZID), toZonalTimestamp(String)

    • toZonalTimestamp

      public PlainTimestamp toZonalTimestamp​(TZID tzid)

      Converts this instance to a local timestamp in given timezone.

      Parameters:
      tzid - timezone id
      Returns:
      local timestamp in given timezone (leap seconds will always be lost)
      Throws:
      IllegalArgumentException - if given timezone cannot be loaded
      Since:
      1.2
      See Also:
      toLocalTimestamp()

    • toZonalTimestamp

      public PlainTimestamp toZonalTimestamp​(String tzid)

      Converts this instance to a local timestamp in given timezone.

      Parameters:
      tzid - timezone id
      Returns:
      local timestamp in given timezone (leap seconds will always be lost)
      Throws:
      IllegalArgumentException - if given timezone cannot be loaded
      Since:
      1.2
      See Also:
      toZonalTimestamp(TZID), toLocalTimestamp()

    • toGeneralTimestamp

      public <C extends Calendrical<?,​ C>> GeneralTimestamp<C> toGeneralTimestamp​(Chronology<C> chronology, TZID tzid, StartOfDay startOfDay)

      Converts this instance to a general timestamp in given timezone.

      Type Parameters:
      C - generic type of date component
      Parameters:
      chronology - chronology of date component
      tzid - timezone id
      startOfDay - start of day
      Returns:
      general timestamp in given timezone (leap seconds will always be lost)
      Throws:
      IllegalArgumentException - if given timezone cannot be loaded
      Since:
      3.8/4.5

    • toGeneralTimestamp

      public <C extends CalendarVariant<C>> GeneralTimestamp<C> toGeneralTimestamp​(CalendarFamily<C> family, String variant, TZID tzid, StartOfDay startOfDay)

      Converts this instance to a general timestamp in given timezone.

      Type Parameters:
      C - generic type of date component
      Parameters:
      family - calendar family for date component
      variant - variant of date component
      tzid - timezone id
      startOfDay - start of day
      Returns:
      general timestamp in given timezone (leap seconds will always be lost)
      Throws:
      IllegalArgumentException - if given timezone cannot be loaded
      ChronoException - if given variant is not recognized
      Since:
      3.8/4.5

    • inLocalView

      public ZonalDateTime inLocalView()

      Creates a combination of this moment and system timezone.

      A direct conversion to a local timestamp can be achieved by toLocalTimestamp().

      Returns:
      moment in system timezone
      Throws:
      IllegalArgumentException - if this moment is a leapsecond and shall be combined with a non-full-minute-timezone-offset
      Since:
      2.0

    • inZonalView

      public ZonalDateTime inZonalView​(TZID tzid)

      Creates a combination of this moment and given timezone.

      A direct conversion to a zonal timestamp can be achieved by toZonalTimestamp(TZID).

      Parameters:
      tzid - timezone id
      Returns:
      moment in given timezone
      Throws:
      IllegalArgumentException - if this moment is a leapsecond and shall be combined with a non-full-minute-timezone-offset or if given timezone cannot be loaded
      Since:
      2.0

    • inZonalView

      public ZonalDateTime inZonalView​(String tzid)

      Creates a combination of this moment and given timezone.

      A direct conversion to a zonal timestamp can be achieved by toZonalTimestamp(String).

      Parameters:
      tzid - timezone id
      Returns:
      moment in given timezone
      Throws:
      IllegalArgumentException - if this moment is a leapsecond and shall be combined with a non-full-minute-timezone-offset or if given timezone cannot be loaded
      Since:
      2.0

    • plus

      public Moment plus​(long amount, SI unit)

      Adds an amount of given SI-unit to this timestamp on the UTC time scale.

      Parameters:
      amount - amount in units to be added
      unit - time unit defined in UTC time space
      Returns:
      changed copy of this instance
      Throws:
      UnsupportedOperationException - if either this moment or the result are before 1972
      ArithmeticException - in case of overflow

    • plus

      public Moment plus​(MachineTime<SI> realTime)

      Adds given real time to this timestamp on the UTC time scale.

      Parameters:
      realTime - real time defined in UTC time space
      Returns:
      changed copy of this instance
      Throws:
      UnsupportedOperationException - if either this moment or the result are before 1972
      ArithmeticException - in case of overflow
      Since:
      3.23/4.19

    • minus

      public Moment minus​(long amount, SI unit)

      Subtracts an amount of given SI-unit from this timestamp on the UTC time scale.

      Parameters:
      amount - amount in SI-units to be subtracted
      unit - time unit defined in UTC time space
      Returns:
      changed copy of this instance
      Throws:
      UnsupportedOperationException - if either this moment or the result are before 1972
      ArithmeticException - in case of overflow

    • minus

      public Moment minus​(MachineTime<SI> realTime)

      Subtracts given real time from this timestamp on the UTC time scale.

      Parameters:
      realTime - real time defined in UTC time space
      Returns:
      changed copy of this instance
      Throws:
      UnsupportedOperationException - if either this moment or the result are before 1972
      ArithmeticException - in case of overflow
      Since:
      3.23/4.19

    • until

      public long until​(Moment end, SI unit)

      Calculates the time distance between this timestamp and given end timestamp in given SI-unit on the UTC time scale.

      Parameters:
      end - end time point
      unit - time unit defined in UTC time space
      Returns:
      count of SI-units between this instance and end time point
      Throws:
      UnsupportedOperationException - if any moment is before 1972

    • print

      public String print​(TemporalFormatter<Moment> printer)

      Creates a formatted output of this instance.

      Parameters:
      printer - helps to format this instance
      Returns:
      formatted string
      Since:
      5.0

    • parse

      public static Moment parse​(String text, TemporalFormatter<Moment> parser)

      Parses given text to an instance of this class.

      Parameters:
      text - text to be parsed
      parser - helps to parse given text
      Returns:
      parsed result
      Throws:
      IndexOutOfBoundsException - if the text is empty
      ChronoException - if the text is not parseable
      Since:
      5.0

    • compareTo

      public int compareTo​(Moment moment)
      Description copied from class: TimePoint

      Compares two time points preferably by their temporal positions on the common time axis.

      Implementation note: In order to make the natural order consistent with equals() the whole state must be taken into account, with preference for those attributes which define the temporal position on the time axis.

      Specified by:
      compareTo in interface Comparable<Moment>
      Specified by:
      compareTo in class TimePoint<TimeUnit,​Moment>
      See Also:
      TimePoint.equals(Object)

    • equals

      public boolean equals​(Object obj)
      Description copied from class: TimePoint

      Compares the whole state of this instance with given object.

      Implementations will usually define their state only based on the temporal position on the time axis because this is the most intuitive approach. Exceptions from this rule should be explicitly documented and reasoned.

      Specified by:
      equals in class TimePoint<TimeUnit,​Moment>
      See Also:
      TimePoint.compareTo(TimePoint)

    • hashCode

      public int hashCode()
      Description copied from class: TimePoint

      Subclasses must redefine this method corresponding to the behaviour of equals().

      Specified by:
      hashCode in class TimePoint<TimeUnit,​Moment>

    • toString

      public String toString()

      Provides a canonical representation in the ISO-format [yyyy-MM-ddTHH:mm:ss,fffffffffZ].

      The fraction will only be printed if not zero. Example: The expression Moment.of(1341100824, 210, TimeScale.UTC) has the representation "2012-06-30T23:59:60,000000210Z".

      Specified by:
      toString in class TimePoint<TimeUnit,​Moment>
      Returns:
      ISO-8601-formatted string

    • toString

      public String toString​(TimeScale scale)

      Creates a formatted view of this instance taking into account given time scale. 

        Moment moment =
      PlainDate.of(2012, Month.JUNE, 30)
      .at(PlainTime.of(23, 59, 59, 999999999))
      .atUTC()
      .plus(1, SI.SECONDS); // move to leap second

  System.out.println(moment.toString(TimeScale.POSIX));
  // Output: POSIX-2012-06-30T23:59:59,999999999Z

  System.out.println(moment.toString(TimeScale.UTC));
  // Output: UTC-2012-06-30T23:59:60,999999999Z

  System.out.println(moment.toString(TimeScale.TAI));
  // Output: TAI-2012-07-01T00:00:34,999999999Z

  System.out.println(moment.toString(TimeScale.GPS));
  // Output: GPS-2012-07-01T00:00:15,999999999Z

  System.out.println(moment.toString(TimeScale.TT));
  // Output: TT-2012-07-01T00:01:07,183999999Z

  System.out.println(moment.toString(TimeScale.UT));
  // Output: UT-2012-07-01T00:00:00,405953024Z
      Parameters:
      scale - time scale to be used for formatting
      Returns:
      formatted string with date-time fields in timezone UTC
      Throws:
      IllegalArgumentException - if this instance is out of range for given time scale
      See Also:
      getElapsedTime(TimeScale), Attributes.TIME_SCALE

    • toTemporalAccessor

      public Instant toTemporalAccessor()
      Description copied from interface: ThreetenAdapter

      Converts this object to a TemporalAccessor.

      Any implementation is required to return a new object with a different concrete type, not this instance.

      Specified by:
      toTemporalAccessor in interface ThreetenAdapter
      Returns:
      converted Threeten-object (always as new object)

    • axis

      public static TimeAxis<TimeUnit,​Moment> axis()

      Provides a static access to the associated time axis respective chronology which contains the chronological rules.

      Returns:
      chronological system as time axis (never null)

    • axis

      public static <S> Chronology<S> axis​(Converter<S,​Moment> converter)

      Provides a static access to the associated time axis using the foreign type S.

      Type Parameters:
      S - foreign temporal type
      Parameters:
      converter - type converter
      Returns:
      chronological system for foreign type
      Since:
      3.24/4.20
      See Also:
      threeten(), TemporalType.JAVA_UTIL_DATE

    • threeten

      public static Chronology<Instant> threeten()

      Obtains a bridge chronology for the type java.time.Instant.

      Returns:
      rule engine adapted for the type java.time.Instant
      Since:
      5.0
      See Also:
      axis()