Interface TimeService

All Known Implementing Classes:
TimeService.DisabledTimeService, TimeService.SystemTimeService
public interface TimeService
Abstraction over time sources.

Direct calls to System.nanoTime() and Instant.now() scatter through the codebase and make unit tests dependent on real time. TimeService centralizes all time reads behind a single interface so that:

  • Tests can supply a controlled implementation with deterministic timestamps.
  • Metrics collection can be disabled at the source

Wall-Clock vs Monotonic Time

The interface provides both kinds of time:

  • now(): wall-clock Instant, suitable for human-readable timestamps.
  • nanos() and interval(long): monotonic nanoseconds, suitable for latency measurement or timeouts. Monotonic time is immune to clock adjustments and NTP drift.

Obtaining an Instance

Use the factory method create(boolean). Pass true to get a live time source backed by the system time source, or false to get a no-op implementation that returns zero/null for all methods.

Since:
2.0
Author:
José Bolina

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final class 
    TimeService.DisabledTimeService
    No-op implementation that returns null for timestamps and 0 for nanosecond values.
    static final class 
    TimeService.SystemTimeService
    Live implementation backed by the JVM time.

  • Method Summary

    Modifier and Type
    Method
    Description
    static TimeService
    create(boolean enabled)
    Creates a TimeService instance.
    long
    interval(long start)
    Computes the elapsed nanoseconds since a previously captured nanos() value.
    long
    nanos()
    Returns a monotonic nanosecond timestamp.
    Instant
    now()
    Returns the current wall-clock time.

  • Method Details

    • now

      Instant now()
      Returns the current wall-clock time.

      Use this for human-readable timestamps. Do not use for latency measurement, wall-clock time is subject to NTP adjustments.

      Returns:
      the current instant, or null when the service is disabled

    • nanos

      long nanos()
      Returns a monotonic nanosecond timestamp.

      Capture a value with nanos() at the start of an operation, then pass it to interval(long) to compute the elapsed time. The absolute value has no meaning outside of interval computation.

      Returns:
      a monotonic nanosecond value, or 0 when disabled

    • interval

      long interval(long start)
      Computes the elapsed nanoseconds since a previously captured nanos() value.

      Typical usage: 

      long start = timeService.nanos();
// ... operation ...
long elapsedNanos = timeService.interval(start);
      Parameters:
      start - a value previously returned by nanos()
      Returns:
      elapsed nanoseconds, or 0 when disabled

    • create

      static TimeService create(boolean enabled)
      Creates a TimeService instance.
      Parameters:
      enabled - true for a live time source, false for a no-op implementation
      Returns:
      a time service backed by system clocks, or a disabled stub that returns zero/null