public final class TimeSample extends Object
TimeSource.A TimeSample is a plain, immutable value object. It carries a single candidate UTC time together with enough context for a consumer to judge how much to trust it and how stale it is:
utc() – the wall-clock time the source believes it is, in UTC.observedAtMonotonic() – the local monotonic reading (System.nanoTime()) captured at the instant the sample was taken, so a consumer can age the sample without trusting any wall clock.confidence() – how much the source itself vouches for the reading.origin() – a short human-readable tag of where it came from (e.g. "ntp:pool.ntp.org", "client:10.0.0.42", "license-manager").precision() – the best precision this reading actually has (nanoseconds, milliseconds or whole seconds).accuracyPercent() – an estimated accuracy/trust of the reading, 0..100.confidence() and accuracyPercent()/precision() answer two different questions and are both used by the aggregator: confidence is "how much do I trust this source at all", while accuracyPercent/precision are "how precise/accurate is this particular reading".
This class contains no licensing logic. It neither decides nor knows whether the time is "good"; it only reports what a source claimed. The decision about whether to trust, aggregate, or reject a sample is made elsewhere by the licensing engine. Keeping this type inert and dumb is deliberate: time-source plumbing lives out here in the open, trust decisions live in the protected part of the license system.
Note the deliberate split between utc() (a wall clock, which can be wrong or even hostile) and observedAtMonotonic() (a monotonic counter, which cannot jump backwards). A consumer ages a sample using the monotonic value, never by comparing two wall-clock readings.
(C) Copyright 2026 Mindus SARL. All rights reserved.
| Modifier and Type | Class and Description |
|---|---|
static class | TimeSample.ConfidenceHow much a TimeSource vouches for a reading. |
static class | TimeSample.PrecisionThe finest resolution at which a reading is meaningful. |
| Constructor and Description |
|---|
TimeSample(Instant utc, long observedAtMonotonic, TimeSample.Confidence confidence, String origin)Creates a time sample with default precision/accuracy. |
TimeSample(Instant utc, long observedAtMonotonic, TimeSample.Confidence confidence, String origin, TimeSample.Precision precision, int accuracyPercent)Creates a time sample with full precision/accuracy detail. |
| Modifier and Type | Method and Description |
|---|---|
int | accuracyPercent()The estimated accuracy/trust of this reading, 0..100. |
TimeSample.Confidence | confidence()The source's own confidence in this reading. |
long | observedAtMonotonic()The local monotonic reading captured when this sample was taken. |
String | origin()A short human-readable tag describing where this reading came from. |
TimeSample.Precision | precision()The best precision this reading actually has. |
String | toString()Returns a trace-friendly description. |
Instant | utc()The UTC time the source believes it is. |
public TimeSample(Instant utc, long observedAtMonotonic, TimeSample.Confidence confidence, String origin, TimeSample.Precision precision, int accuracyPercent)
utc - The UTC time the source believes it is (must not be null).observedAtMonotonic - The System.nanoTime() value captured when the reading was taken; used to age the sample safely.confidence - The source's own confidence (must not be null).origin - A short origin tag for tracing (must not be null).precision - The best precision this reading has (must not be null).accuracyPercent - Estimated accuracy/trust, clamped to 0..100.public TimeSample(Instant utc, long observedAtMonotonic, TimeSample.Confidence confidence, String origin)
Kept for backward compatibility; delegates to the richer constructor with TimeSample.Precision.MILLIS and an unspecified accuracy of 0. New callers should use the six-argument constructor and supply a real precision and accuracy.
utc - The UTC time the source believes it is (must not be null).observedAtMonotonic - The System.nanoTime() value captured when the reading was taken; used to age the sample safely.confidence - The source's own confidence (must not be null).origin - A short origin tag for tracing (must not be null).public Instant utc()
public long observedAtMonotonic()
This is a System.nanoTime() value: meaningful only as a difference against another nanoTime() reading on the same JVM run, never as an absolute time. Use it to compute how old a sample is without trusting any wall clock.
public TimeSample.Confidence confidence()
public String origin()
"ntp:pool.ntp.org".public TimeSample.Precision precision()
public int accuracyPercent()
Guidance for typical sources: a good NTP reading is near 100; a License Manager around 80; a peer (load-balanced) NetPhantom Server around 70; a remote NetPhantom client around 50. NTP derives its value from the packet (stratum, root dispersion, round-trip delay); socket-peer values are fixed defaults.
Phantom® and NetPhantom® are registered trademarks of Mindus SARL.
© 2026 Mindus SARL. All rights reserved.