Class MonotonicClock

java.lang.Object
java.time.Clock
org.apache.maven.api.MonotonicClock
All Implemented Interfaces:
InstantSource
public class MonotonicClock extends Clock
A Clock implementation that combines monotonic timing with wall-clock time.

This class provides precise time measurements using System.nanoTime() while maintaining wall-clock time information in UTC. The wall-clock time is computed from the monotonic duration since system start to ensure consistency between time measurements.

This implementation uses UTC timezone for the singleton instance. Timezone variants can be created via withZone(ZoneId) while maintaining the same monotonic timing base. Users needing local time representation can either use withZone(ZoneId) or convert the result of instant() to their desired timezone: 

Instant now = MonotonicClock.now();
ZonedDateTime local = now.atZone(ZoneId.systemDefault());
See Also:

  • Method Details

    • get

      public static MonotonicClock get()
      Returns the singleton instance of MonotonicClock.
      Returns:
      the monotonic clock instance

    • now

      public static Instant now()
      Returns the current instant from the monotonic clock. This is a convenience method equivalent to get().instant().
      Returns:
      the current instant using monotonic timing

    • start

      public static Instant start()
      Returns the initialization time of this monotonic clock. This is a convenience method equivalent to get().start().
      Returns:
      the instant when this monotonic clock was initialized
      See Also:

    • elapsed

      public static Duration elapsed()
      Returns the elapsed time since clock initialization. This is a convenience method equivalent to get().elapsedTime().
      Returns:
      the duration since clock initialization

    • instant

      public Instant instant()
      Returns a monotonically increasing instant.

      The returned instant is calculated by adding the elapsed nanoseconds since clock creation to the initial wall clock time. This ensures that the time never goes backwards and maintains a consistent relationship with the wall clock time.

      Specified by:
      instant in interface InstantSource
      Specified by:
      instant in class Clock
      Returns:
      the current instant using monotonic timing

    • startInstant

      public Instant startInstant()
      Returns the wall clock time captured when this monotonic clock was initialized.

      This instant serves as the base time from which all subsequent instant() calls are calculated by adding the elapsed monotonic duration. This ensures consistency between the monotonic measurements and wall clock time.

      Returns:
      the initial wall clock instant when this clock was created
      See Also:

    • elapsedTime

      public Duration elapsedTime()
      Returns the duration elapsed since this clock was initialized.

      The returned duration is calculated using System.nanoTime() to ensure monotonic behavior. This duration represents the exact time span between clock initialization and the current instant.

      Returns:
      the duration since clock initialization
      See Also:

    • getZone

      public ZoneId getZone()
      Returns the zone ID of this clock.

      The singleton instance always returns UTC. Clock instances created via withZone(ZoneId) return their configured timezone.

      Specified by:
      getZone in class Clock
      Returns:
      the zone ID

    • withZone

      public Clock withZone(ZoneId zone)
      Returns a copy of this clock with the specified timezone.

      Since Instant instances are timezone-agnostic and the monotonic property derives from System.nanoTime(), the returned clock maintains identical monotonic timing but reports the requested timezone.

      Specified by:
      withZone in interface InstantSource
      Specified by:
      withZone in class Clock
      Parameters:
      zone - the target timezone, not null
      Returns:
      a new clock with the specified timezone
      Throws:
      NullPointerException - if zone is null