public final class SntpClient extends Object
It issues a single UDP query to one NTP server, builds and parses the 48-byte NTP packet by hand, and computes the standard clock offset and round-trip delay from the four timestamps. From the packet it also reads the stratum, the server precision, and the root dispersion, and from those it derives an accuracyPercent and a TimeSample.Precision for the produced NtpTimeSample.
This class intentionally does not do multi-server polling, outlier rejection, or OS-clock discipline. It only reads a trustworthy time. The robustness a "full" NTP client would add (cross-checking several servers) lives in the aggregator that consumes the samples; pointing this client at a list of servers and aggregating the results is the multi-server story. See NtpPoller.
The destination port and the accuracy/confidence heuristics are supplied as an immutable SntpTuning (defaulting to NTP_PORT and the DEFAULT_* values). The server side reads and clamps those from server.ini; this class itself reads no configuration.
Pure JDK, Java 8 through 25+, no third-party dependencies. Each query(java.lang.String) call is self-contained and uses its own short-lived socket, so a single SntpClient instance is safe to share across threads.
(C) Copyright 2026 Mindus SARL. All rights reserved.
| Modifier and Type | Field and Description |
|---|---|
static int | DEFAULT_CONFIDENCE_HIGH_ATDefault accuracy at or above which the reading is rated HIGH confidence. |
static int | DEFAULT_CONFIDENCE_MEDIUM_ATDefault accuracy at or above which the reading is rated MEDIUM confidence. |
static int | DEFAULT_MAX_DISPERSION_PENALTYDefault maximum accuracy lost to root dispersion (reached at >= 1 second). |
static int | DEFAULT_MAX_RTT_PENALTYDefault maximum accuracy lost to round-trip delay (reached at >= 0.5 second). |
static int | DEFAULT_PENALTY_PER_STRATUMDefault accuracy lost per stratum beyond the primary reference (stratum 1). |
static int | NTP_PORTStandard NTP UDP port. |
| Constructor and Description |
|---|
SntpClient(int timeoutMs)Creates a client with a query timeout and the default port and heuristics. |
SntpClient(int timeoutMs, SntpTuning tuning)Creates a client with a query timeout and explicit tuning (port and accuracy heuristics). |
| Modifier and Type | Method and Description |
|---|---|
NtpTimeSample | query(String host)Queries one NTP server and returns the reading, or null if the query failed or the response was unusable (no reply, malformed packet, kiss-o'-death, or an unsynchronized server). |
public static final int NTP_PORT
public static final int DEFAULT_PENALTY_PER_STRATUM
public static final int DEFAULT_MAX_DISPERSION_PENALTY
public static final int DEFAULT_MAX_RTT_PENALTY
public static final int DEFAULT_CONFIDENCE_HIGH_AT
public static final int DEFAULT_CONFIDENCE_MEDIUM_AT
public SntpClient(int timeoutMs)
timeoutMs - Socket receive timeout in milliseconds (must be > 0).public SntpClient(int timeoutMs,
SntpTuning tuning)timeoutMs - Socket receive timeout in milliseconds (must be > 0).tuning - The port and accuracy/confidence heuristics (must not be null).public NtpTimeSample query(String host)
null if the query failed or the response was unusable (no reply, malformed packet, kiss-o'-death, or an unsynchronized server).This call blocks for at most the configured timeout. It must therefore be run on a background thread (see NtpPoller), never inline on a request path.
host - The NTP server host name or address (must not be null).NtpTimeSample, or null when nothing trustworthy was obtained.Phantom® and NetPhantom® are registered trademarks of Mindus SARL.
© 2026 Mindus SARL. All rights reserved.