net.time4j.clock.SntpConfiguration Maven / Gradle / Ivy

Go to download
/*
 * -----------------------------------------------------------------------
 * Copyright © 2013-2015 Meno Hochschild, 
 * -----------------------------------------------------------------------
 * This file (SntpConfiguration.java) is part of project Time4J.
 *
 * Time4J is free software: You can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published
 * by the Free Software Foundation, either version 2.1 of the License, or
 * (at your option) any later version.
 *
 * Time4J is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with Time4J. If not, see .
 * -----------------------------------------------------------------------
 */

package net.time4j.clock;


/**
 * Represents a configuration for a connection to a NTP-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     java.util.ServiceLoader
 * @doctags.spec    Implementations must have a public constructor without any arguments.
 */
/*[deutsch]
 * Repräsentiert eine Konfiguration für eine Verbindung zu
 * einem NTP-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     java.util.ServiceLoader
 * @doctags.spec    Implementations must have a public constructor without any arguments.
 */
public interface SntpConfiguration
    extends NetTimeConfiguration {

    //~ Methoden ----------------------------------------------------------

    /**
     * Determines if NTP3 or NTP4 should be used. 
     *
     * @return  {@code true} if NTP4 shall be used else {@code false}
     * @since   2.1
     */
    /*[deutsch]
     * Bestimmt, ob NTP3 oder NTP4 verwendet werden soll. 
     *
     * @return  {@code true} wenn NTP4 Verwendung findet, sonst {@code false}
     * @since   2.1
     */
    boolean isNTP4();

    /**
     * Determines the rate by which a SNTP-client sends queries during
     * a connection for the purpose of the calculation of an arithmetic
     * mean value. 
     *
     * Default value is {@code 60 * 4} (that is 4 minutes). This method
     * is only relevant if {@code getRequestCount()} yields at least the
     * value {@code 2}. One single connection request can contain several
     * queries this way. Note that some servers will block requests if
     * they happen too often. 
     *
     * @return  time distance between two messages in seconds as positive number
     * @since   2.1
     */
    /*[deutsch]
     * Bestimmt die Rate, mit der ein SNTP-Client während einer
     * Verbindung Anfragen sendet, um dann über die Ergebnisse zu
     * mitteln. 
     *
     * Standardwert ist {@code 60 * 4} (respektive 4 Minuten). Diese Methode
     * ist nur dann von Bedeutung, wenn {@code getRequestCount()} mindestens
     * den Wert {@code 2} liefert. Ein einzelnes Verbindungsereignis (CONNECT)
     * kann also mehrere Teilanfragen enthalten. 
     *
     * @return  zeitlicher Abstand zwischen zwei Nachrichten in Sekunden als
     *          positive Zahl
     * @since   2.1
     */
    int getRequestInterval();

    /**
     * Determines how often a SNTP-Client will send queries during a
     * connection for the purpose of the calculation of an arithmetic
     * mean value. 
     *
     * Default value is {@code 1} (single query). The value {@code 0}
     * is also permitted and effectively stops any query. If any bigger
     * value ({@code > 1}) is configured then an asynchronous connection
     * to the NTP-server is recommended. One single connection request can
     * contain several queries this way. Note that some servers will block
     * requests if they happen too often. 
     *
     * @return  number in range {@code 0 <= x < 1000}
     * @since   2.1
     * @see     SntpConnector#connect()
     */
    /*[deutsch]
     * Bestimmt, wie oft ein SNTP-Client während einer Verbindung
     * Anfragen sendet, um dann über die Ergebnisse zu mitteln. 
     *
     * Standardwert ist {@code 1} (einmalige Anfrage). Der Wert {@code 0}
     * ist auch zugelassen und führt zum Abschalten der Anfragen. Wird
     * ein größerer Wert ({@code > 1}) konfiguriert, empfiehlt sich
     * eine asynchrone Verbindung zum NTP-Server in einem separaten Thread.
     * Ein einzelnes Verbindungsereignis (CONNECT) kann also mehrere Anfragen
     * enthalten. 
     *
     * @return  Zahl im Bereich {@code 0 <= x < 1000}
     * @since   2.1
     * @see     SntpConnector#connect()
     */
    short getRequestCount();

}