Package net.time4j

Class SystemClock

java.lang.Object
net.time4j.SystemClock
All Implemented Interfaces:
TimeSource<Moment>
public final class SystemClock extends Object implements TimeSource<Moment>

Represents a clock which is based on the clock of the underlying operating system.

Author:
Meno Hochschild

  • Field Details

    • INSTANCE

      public static final SystemClock INSTANCE

      Standard implementation.

      The system property "net.time4j.systemclock.nanoTime" controls if this clock is internally based on the expression System.nanoTime() (if property is set to "true") or System.currentTimeMillis() (default). The standard case is a clock which is affected by OS-triggered time jumps and user adjustments so there is no guarantee for a monotonic time.

    • MONOTONIC

      public static final SystemClock MONOTONIC

      Monotonic clock based on the best available clock of the underlying operating system.

      A side effect of this implementation can be increased nominal precision up to nanoseconds although no guarantee is made to ensure nanosecond accuracy. The accuracy is often limited to milliseconds. However, the main focus and motivation is realizing a monotonic behaviour by delegating to the use of a monotonic clock of the underlying OS. Equivalent to CLOCK_MONOTONIC on a Linux-server.

      Since:
      3.2/4.1
      See Also:
      TickProvider.getNanos()

  • Method Details

    • currentTime

      public Moment currentTime()
      Description copied from interface: TimeSource

      Yields the current time.

      Specified by:
      currentTime in interface TimeSource<Moment>
      Returns:
      current time in seconds (as UnixTime object or derivate)

    • currentTimeInMillis

      public long currentTimeInMillis()

      Yields the current time in milliseconds elapsed since [1970-01-01T00:00:00,000Z].

      Returns:
      count of milliseconds since UNIX epoch without leap seconds
      See Also:
      currentTimeInMicros()

    • currentTimeInMicros

      public long currentTimeInMicros()

      Yields the current time in microseconds elapsed since [1970-01-01T00:00:00,000000Z].

      If this clock is based only on System.currentTimeMillis() then this method will just multiply the millisecond value by factor 1000. On many operating systems the precision is limited to milliseconds. This is even true if this clock is based on System.nanoTime() because for purpose of calibration even here the method System.currentTimeMillis() must be accessed at least one time.

      Returns:
      count of microseconds since UNIX epoch without leap seconds

    • realTimeInMicros

      public long realTimeInMicros()

      Yields the current time in microseconds elapsed since UTC epoch [1972-01-01T00:00:00,000000Z].

      Returns:
      count of microseconds since UTC epoch including leap seconds
      Since:
      3.2/4.1
      See Also:
      currentTimeInMicros()

    • inPlatformView

      public static ZonalClock inPlatformView()

      Creates a local clock in the platform timezone.

      Uses the standard clock SystemClock.INSTANCE and the platform timezone data.

      Background: Some mobile devices might have outdated or wrong timezone data but still display the correct local time because they compensate the wrong zone information by adjusting the clock. This method can help in such a situation, for example: 

           // we assume/know that the local device time is correct...
     PlainTimestamp localTimestamp = SystemClock.inPlatformView().now();
     // ...and then we combine correct local device time with the valid timezone data of Time4J
     Moment nowCorrect = localTimestamp.inStdTimezone();
      Returns:
      local clock in system timezone using the platform timezone data
      Since:
      3.3/4.2
      See Also:
      Timezone.ofPlatform(), ZonalClock.now(), INSTANCE

    • inLocalView

      public static ZonalClock inLocalView()

      Creates a local clock in system timezone.

      Uses the standard clock SystemClock.INSTANCE.

      Returns:
      cached local clock in system timezone using the best available timezone data
      See Also:
      Timezone.ofSystem(), INSTANCE

    • inZonalView

      public static ZonalClock inZonalView​(TZID tzid)

      Creates a local clock in given timezone.

      In order to achieve a monotonic zonal clock, users can use the expression new ZonalClock(SystemClock.MONOTONIC, tzid).

      Parameters:
      tzid - timezone id
      Returns:
      local clock in given timezone
      Throws:
      IllegalArgumentException - if given timezone cannot be loaded
      See Also:
      INSTANCE

    • inZonalView

      public static ZonalClock inZonalView​(String tzid)

      Creates a local clock in given timezone.

      In order to achieve a monotonic zonal clock, users can use the expression new ZonalClock(SystemClock.MONOTONIC, tzid).

      Parameters:
      tzid - timezone id
      Returns:
      local clock in given timezone
      Throws:
      IllegalArgumentException - if given timezone cannot be loaded
      See Also:
      INSTANCE

    • currentMoment

      public static Moment currentMoment()

      Equivalent to SystemClock.INSTANCE.currentTime().

      Returns:
      current time using the standard implementation
      Since:
      2.3
      See Also:
      INSTANCE

    • recalibrated

      public SystemClock recalibrated()

      Recalibrates this instance and yields a new copy.

      This method is only relevant if this clock is operated in monotonic mode. It is strongly advised not to recalibrate during or near a leap second. Please also note that this method might cause jumps in time - even backwards.

      Returns:
      new and recalibrated copy of this instance
      Since:
      3.2/4.1
      See Also:
      MONOTONIC

    • synchronizedWith

      public SystemClock synchronizedWith​(TimeSource<?> clock)

      Synchronizes this instance with given time source and yields a new copy.

      This method is only relevant if this clock is operated in monotonic mode. It is strongly advised not to recalibrate during or near a leap second. Please also note that this method might cause jumps in time - even backwards.

      Parameters:
      clock - another clock which this instance should be synchronized with
      Returns:
      synchronized copy of this instance
      Since:
      3.2/4.1
      See Also:
      MONOTONIC