net.time4j.engine.StartOfDay Maven / Gradle / Ivy

Go to download
/*
 * -----------------------------------------------------------------------
 * Copyright © 2013-2014 Meno Hochschild, 
 * -----------------------------------------------------------------------
 * This file (StartOfDay.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.engine;


/**
 * Defines the start of a calendar day. 
 * 
 * Background is the fact that some calendar systems start
 * calendar days at another time than midnight. For example the
 * islamic calendars start the day at sunset on previous day. 
 *
 * @author  Meno Hochschild
 */
/*[deutsch]
 * Definiert den Beginn des Tages. 
 * 
 * Hintergrund ist die Tatsache, daß einige Kalendersystem
 * den Tag zu einer anderen Zeit als Mitternacht starten. Zum
 * Beispiel fangen die islamischen Kalender den Tag zum
 * Sonnenuntergang am Vortag an. 
 *
 * @author  Meno Hochschild
 */
public interface StartOfDay {

    //~ Statische Felder/Initialisierungen --------------------------------

    /**
     * The calendar day starts at midnight. 
     *
     * This setting is valid for all ISO-8601-systems by default. An
     * exception are certain timezones where days might start later than
     * midnight due to daylight-saving-change, for example in Brazil. 
     */
    /*[deutsch]
     * Der Tag fängt um Mitternacht an. 
     *
     * Diese Einstellung gilt standardmäßig für alle
     * ISO-8601-konformen Datumsangaben. Eine Ausnahme sind allerdings in
     * bestimmten Zeitzonen auch im ISO-Standard Tage, die wegen einer
     * Sommerzeitumstellung erst nach Mitternacht starten, zum Beispiel
     * in Brasilien. 
     */
    static final StartOfDay MIDNIGHT =
        new StartOfDay() {
            @Override
            public int getShift(long epochDays) {
                return 0;
            }
            @Override
            public boolean isFixed() {
                return true;
            }
        };

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

    /**
     * Queries the start time of given calendar day in seconds
     * relative to midnight (UTC). 
     *
     * Example: In Israel the legal hebrew calendar day starts at
     * 6 PM on previous day, so the shift is negative with the value
     * {@code -6 * 60 * 60}. In a religious context the concrete time
     * of sunset is important so the given argument can be used to
     * calculate the season-dependent position of the sun. 
     *
     * @param   epochDays   count of days relative to UTC epoch [1972-01-01]
     * @return  shift in seconds relative to midnight (positive or negative)
     */
    /*[deutsch]
     * Ermittelt die Startzeit des angegebenen Tages in Sekunden relativ
     * zu Mitternacht (UTC). 
     *
     * Beispiel: In Israel fängt der hebräische Tag gesetzlich
     * bereits um 18 Uhr am Vortag an, also ist die Verschiebung negativ mit
     * dem Wert {@code -6 * 60 * 60}. Im religiösen Verwendungskontext
     * muß sogar die konkrete Uhrzeit des Sonnenuntergangs herangezogen
     * werden. In letzterem Fall wird für die erforderliche astronomische
     * Berechnung das Argument zur saisonalen Bestimmung des Sonnenstands
     * benutzt. 
     *
     * @param   epochDays   count of days relative to UTC epoch [1972-01-01]
     * @return  shift in seconds relative to midnight (positive or negative)
     */
    int getShift(long epochDays);

    /**
     * Queries if the start of a calendar day always happens at the
     * same time. 
     *
     * @return  {@code true} if the day always starts at the same wall time
     *          else {@code false}
     */
    /*[deutsch]
     * Erfolgt der Tagesbeginn immer zu einer festen Uhrzeit? 
     *
     * @return  {@code true} if the day always starts at the same wall time
     *          else {@code false}
     */
    boolean isFixed();

}