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

Go to download
Show more of this group Show more artifacts with this name
Show all versions of time4j-core Show documentation
There is a newer version: 4.38
/*
 * -----------------------------------------------------------------------
 * Copyright © 2013-2016 Meno Hochschild, 
 * -----------------------------------------------------------------------
 * This file (CalendarEra.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;


/**
 * Represents an era in a calendar system. 
 *
 * An era is date-related and defines a reference date which can be
 * interpreted as start or end of an era. Not all calendar systems know
 * an era concept, however. Especially all ISO-calendar systems have no
 * era according to ISO-8601-standard. If an era exists in a given
 * calendar system then the meaning of a year changes such that it
 * means the year of an era counting as positive number from {@code >= 1}. 
 *
 * @author  Meno Hochschild
 */
/*[deutsch]
 * Repräsentiert eine Ära in einem Kalendersystem. 
 *
 * Eine Ära ist grundsätzlich datumsbezogen und definiert ein
 * Bezugsdatum, das als Beginn oder Ende der Ära interpretiert werden
 * kann. Nicht alle Kalender kennen überhaupt eine Ära, insbesondere
 * alle ISO-Kalendersysteme haben dieses Konzept nicht. Wenn eine Ära
 * existiert, verändert sich die Bedeutung einer Jahresangabe im
 * jeweiligen Kalendersystem dahingehend, daß die Jahresangabe dann
 * als Jahr innerhalb einer Ära zu interpretieren ist. Jahre innerhalb
 * einer Ära sind grundsätzlich positive Zahlen {@code >= 1}. 
 *
 * @author  Meno Hochschild
 */
public interface CalendarEra {

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

    /**
     * Yields the canonical non-localized name. 
     *
     * @return  String
     */
    /*[deutsch]
     * Liefert den kanonischen nicht lokalisierten Namen. 
     *
     * @return  String
     */
    String name();

    /**
     * Yields an ordinal number which is scaled such that every era
     * which contains the ISO-date of UTC-epoch [1972-01-01] will have
     * the associated value {@code 1}. 
     *
     * Attention: This number is neither necessarily unique nor
     * does it imply any chronological order. 
     *
     * @return  int
     * @deprecated  no replacement in next major release because it is not useful
     */
    /*[deutsch]
     * Liefert eine Ordnungsnummer, die so skaliert ist, daß
     * jede Ära, die das ISO-Datum der UTC-Epoche [1972-01-01]
     * enthält, den Wert {@code 1} ergibt. 
     *
     * Achtung: Die so definierte Ordnungsnummer ist weder zwingend eindeutig
     * noch legt sie irgendeine zeitliche Ordnung fest. 
     *
     * @return  int
     * @deprecated  no replacement in next major release because it is not useful
     */
    @Deprecated
    int getValue();

}