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 is singleton-based and always uses UTC timezone. The clock cannot be adjusted to different timezones to maintain consistent monotonic behavior. Users needing local time representation should 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, which is always UTC.
      Specified by:
      getZone in class Clock
      Returns:
      the UTC zone ID

    • withZone

      public Clock withZone(ZoneId zone)
      Returns this clock since timezone adjustments are not supported.

      This implementation maintains UTC time to ensure monotonic behavior. The provided zone parameter is ignored.

      Specified by:
      withZone in interface InstantSource
      Specified by:
      withZone in class Clock
      Parameters:
      zone - the target timezone (ignored)
      Returns:
      this clock instance