Class NtpTimeSource
- All Implemented Interfaces:
TimeSource
TimeSource corrected against an NTP server.
One clean protocol, one UDP round trip: the offset between the OS clock and the server's is measured and applied, and re-measured on an interval. This is the library's only non-HTTP network shape, and it is deliberately minimal — a single SNTP exchange with the standard four-timestamp offset calculation, not an aggregator over a handful of web time APIs that each answer in a different JSON shape and are slower than the drift they claim to fix.
Its UDP exchange does not go through the runtime's ProxyProvider. NTP is
not HTTP, and no proxy route the library knows carries it, so a host that proxies every request still
sends this one from its own address to the server named here; see SECURITY.md. A host that must not
do that passes its own TimeSource instead.
now() never touches the network. It is the OS clock plus the last measured
offset — pure arithmetic — because it is read inside the final spin of a scheduled claim, where a DNS
lookup or a socket timeout turns a twenty-millisecond approach into seconds and misses the target.
Measurement happens off to the side: a now() that finds the offset due for a re-measure starts
one on the executor it was given and returns at once with what it already has. A failed measurement keeps the
last good offset (or zero, if none was ever obtained) and is retried on a growing backoff rather than
on every call — a claim should fire on a slightly-off clock rather than not at all. A caller that
wants the correction in hand before it schedules anything calls sync() first, which does
block.
A reply is only believed if it is a server reply to this request: server mode, a real stratum, a set clock, and the request's own random nonce echoed back, so a stray or forged datagram cannot move the clock.
- Since:
- 0.11.0
-
Constructor Summary
ConstructorsConstructorDescriptionNtpTimeSource(Executor executor) Creates a source correcting againstpool.ntp.org, re-syncing every 15 minutes.NtpTimeSource(Executor executor, String server, int port, Duration resyncInterval) Creates a source correcting against a server on a given port — for a host running its own time server somewhere other than the standard port.NtpTimeSource(Executor executor, String server, Duration resyncInterval) Creates a source correcting against a given server on a given interval. -
Method Summary
Modifier and TypeMethodDescriptionnow()Returns the OS clock corrected by the last measured offset.offset()Returns the correction currently applied to the OS clock.booleansync()Measures the offset now, blocking until the exchange finishes or times out, so a caller about to schedule a time-critical claim has the correction in hand before the firstnow().booleansynced()Returns whether an offset has ever been measured.
-
Constructor Details
-
NtpTimeSource
Creates a source correcting againstpool.ntp.org, re-syncing every 15 minutes.- Parameters:
executor- the executor background measurements run on- Since:
- 1.0.0
-
NtpTimeSource
Creates a source correcting against a given server on a given interval.- Parameters:
executor- the executor background measurements run onserver- the NTP server hostnameresyncInterval- how often to re-measure the offset; null or non-positive means 15 minutes- Since:
- 1.0.0
-
NtpTimeSource
Creates a source correcting against a server on a given port — for a host running its own time server somewhere other than the standard port.- Parameters:
executor- the executor background measurements run onserver- the NTP server hostnameport- the UDP port the server answers onresyncInterval- how often to re-measure the offset; null or non-positive means 15 minutes- Since:
- 1.0.0
-
-
Method Details
-
now
Returns the OS clock corrected by the last measured offset. Never blocks and never touches the network: when the offset is due for a re-measure this starts one in the background and returns with the offset it already has, which is zero until the first measurement lands.- Specified by:
nowin interfaceTimeSource- Returns:
- now, corrected by the last known offset
- Since:
- 0.11.0
-
sync
public boolean sync()Measures the offset now, blocking until the exchange finishes or times out, so a caller about to schedule a time-critical claim has the correction in hand before the firstnow().Measurements are serialised: a call made while another is in flight waits for it and then measures in turn.
- Returns:
- true if the sync succeeded
- Since:
- 0.11.0
-
synced
public boolean synced()Returns whether an offset has ever been measured. Until it has,now()is the uncorrected OS clock.- Returns:
- true once a measurement has succeeded
- Since:
- 0.12.0
-
offset
Returns the correction currently applied to the OS clock.- Returns:
- the last measured offset, zero before the first successful measurement
- Since:
- 0.12.0
-