net.time4j.clock.NetTimeConfiguration Maven / Gradle / Ivy
/*
* -----------------------------------------------------------------------
* Copyright © 2013-2015 Meno Hochschild, Contains the configuration parameters of a connection to an internet
* time server.
*
* Implementations of this SPI-interface must be
* immutable or at least threadsafe. Instances can be
* created manually or via a {@code ServiceLoader}.
*
* @author Meno Hochschild
* @since 2.1
* @see NetTimeConnector
* @see java.util.ServiceLoader
* @doctags.spec Implementations must have a public constructor without any arguments.
*/
/*[deutsch]
* Enthält die Konfiguration einer Verbindung zu einem
* Internet-Uhrzeit-Server.
*
* Implementierungen dieses SPI-Interface müssen
* immutable oder wenigstens threadsafe sein. Instanzen werden
* manuell oder über einen {@code ServiceLoader}-Mechanismus erzeugt.
*
* @author Meno Hochschild
* @since 2.1
* @see NetTimeConnector
* @see java.util.ServiceLoader
* @doctags.spec Implementations must have a public constructor without any arguments.
*/
public interface NetTimeConfiguration {
//~ Statische Felder/Initialisierungen --------------------------------
/**
* Default timeout is {@code 60} seconds.
*/
/*[deutsch]
* Standardwartezeit: {@code 60} Sekunden.
*/
static final int DEFAULT_CONNECTION_TIMEOUT = 60;
//~ Methoden ----------------------------------------------------------
/**
* Yields the internet address of a time server.
*
* Possible values are also addresses of older time servers which
* still support the elder protocol (RFC 867), for example:
*
* - time.nist.gov (US-government)
* - time.ien.it (electrotechn. institute in Italy)
*
* Alternatively, addresses of modern NTP-servers are permitted
* which support the protocols NTP3 or NTP4:
*
* - ptbtime1.ptb.de
* - ptbtime2.ptb.de
* - ntp2.lrz-muenchen.de
*
* @return time server address
* @since 2.1
*/
/*[deutsch]
* Liefert die Internet-Adresse eines Uhrzeit-Servers.
*
* Mögliche Eigenschaftenwerte sind auch die Adressen von
* Uhrzeit-Servern im Netz, die noch das ältere Protokoll
* unterstützen (RFC 867), zum Beispiel:
*
* - time.nist.gov (US-Regierung)
* - time.ien.it (elektrotechn. Institut in Italien)
*
* Alternativ sind die Adressen von moderneren NTP-Servern
* möglich, die die Protokolle NTP3 oder NTP4 unterstützen:
*
* - ptbtime1.ptb.de
* - ptbtime2.ptb.de
* - ntp2.lrz-muenchen.de
*
* @return Uhrzeit-Server-Adresse
* @since 2.1
*/
String getTimeServerAddress();
/**
* Yields the port of a time server.
*
* The DAYTIME-protocol assumes as default value {@code 13} while
* NTP-protocols usually use the value {@code 123}.
*
* @return int
* @since 2.1
*/
/*[deutsch]
* Liefert den Port des Uhrzeit-Servers.
*
* Als Standardwerte werden für das DAYTIME-Protokoll der Wert
* {@code 13} und für die NTP-Protokolle der Wert {@code 123}
* verwendet.
*
* @return int
* @since 2.1
*/
int getTimeServerPort();
/**
* Determines the maximum time out when connecting to an internet
* time server.
*
* The value {@code 0} indicates an unlimited waiting time. The
* default value is internally {@code 60} seconds.
*
* @return maximum waiting time in seconds {@code >= 0}
* @since 2.1
* @see #DEFAULT_CONNECTION_TIMEOUT
*/
/*[deutsch]
* Gibt die maximale Wartezeit beim Verbindungsaufbau an.
*
* Der Wert {@code 0} zeigt eine unbegrenzte Wartezeit an. Als
* Standardwert gilt intern immer {@code 60} Sekunden.
*
* @return maximum waiting time in seconds {@code >= 0}
* @since 2.1
* @see #DEFAULT_CONNECTION_TIMEOUT
*/
int getConnectionTimeout();
/**
* Determines the time window within which an existing shift between
* the local clock and the internet clock will be synchronized (after
* a successful connection) if the local clock is too quick.
*
* The value {@code 0} causes the immediate synchronization and is the
* default. Else the local clock will only be synchronized with the
* internet clock after this clock shift window has been passed. Within
* this time window the local clock will be slowly adjusted to the internet
* clock. The time window should always be choosen such that it is smaller
* than the time between two connections. Its main purpose is slowing
* down a local clock such that applications will not notice any
* backwards running time within the scope of expected precision.
*
* If the local clock is too slow however then the synchronization
* will happen immediately, and this configuration parameter is not
* applied.
*
* @return time window in seconds ({@code >= 0})
* @since 2.1
*/
/*[deutsch]
* Legt das Zeitfenster fest, innerhalb dessen nach einer erfolgreichen
* Verbindung ein bestehender Offset zwischen lokaler Uhr und Internet-Uhr
* synchronisiert wird, wenn die lokale Uhr der Internet-Uhr vorauszueilen
* droht.
*
* Der Wert {@code 0} führt zur sofortigen Anpassung des Offset
* und ist Standardvorgabe. Sonst wird die lokale Uhr erst nach Ablauf
* des Zeitfensters mit der Internet-Uhr nachgezogen sein. Während
* des Zeitfensters findet eine graduelle Anpassung statt. Das Zeitfenster
* sollte immer kleiner als die Zeit zwischen zwei Verbindungen sein
* und dient dazu, eine lokale Uhr so langsam abzubremsen, daß
* Anwendungen innerhalb der von ihnen erwarteten Genauigkeit keine
* rückläufige Zeit bemerken. War die lokale Uhr hingegen zu
* langsam, findet immer eine sofortige Anpassung statt, und diese
* Konfigurationseigenschaft spielt dann keine Rolle.
*
* @return Zeitfenster in Sekunden ({@code >= 0})
* @since 2.1
*/
int getClockShiftWindow();
}