Package net.time4j.history

Class ChronoHistory

java.lang.Object
net.time4j.history.ChronoHistory
All Implemented Interfaces:
Serializable, VariantSource
public final class ChronoHistory extends Object implements VariantSource, Serializable

Represents the chronological history of calendar reforms in a given region.

All non-proleptic history objects are limited to the range BC 45 until the year AD 9999.

Since:
3.0
Author:
Meno Hochschild
See Also:
Serialized Form

  • Field Details

    • YEAR_DEFINITION

      public static final AttributeKey<YearDefinition> YEAR_DEFINITION
      Format attribute controlling the type of historic year used in parsing or formatting.
      Since:
      3.18/4.14

    • PROLEPTIC_GREGORIAN

      public static final ChronoHistory PROLEPTIC_GREGORIAN

      Describes no real historic event but just the proleptic gregorian calendar which is assumed to be in power all times.

      This constant rather serves for academic purposes. Users will normally use PlainDate without an era.

    • PROLEPTIC_JULIAN

      public static final ChronoHistory PROLEPTIC_JULIAN

      Describes no real historic event but just the proleptic julian calendar which is assumed to be in power all times (with the technical constraint BC 999979466 - AD 999979465).

      This constant rather serves for academic purposes because the julian calendar is now nowhere in power and has not existed before the calendar reform of Julius Caesar.

    • PROLEPTIC_BYZANTINE

      public static final ChronoHistory PROLEPTIC_BYZANTINE

      Describes no real historic event but just the proleptic byzantine calendar which is assumed to be in power all times from the creation of the world until the byzantine year 999984973.

      This constant rather serves for academic purposes because the byzantine calendar was in latest use in Russia before 1700.

      Since:
      3.14/4.11
      See Also:
      HistoricEra.BYZANTINE

  • Method Details

    • ofFirstGregorianReform

      public static ChronoHistory ofFirstGregorianReform()

      Describes the original switch from julian to gregorian calendar introduced by pope Gregor on 1582-10-15.

      Returns:
      chronological history with cutover to gregorian calendar on 1582-10-15
      Since:
      3.0
      See Also:
      ofGregorianReform(PlainDate)

    • ofGregorianReform

      public static ChronoHistory ofGregorianReform​(PlainDate start)

      Describes a single switch from julian to gregorian calendar at given date.

      Since version 3.1 there are two special cases to consider. If the given date is the maximum/minimum of the date axis then this method will return the proleptic julian/gregorian ChronoHistory.

      Parameters:
      start - calendar date when the gregorian calendar was introduced
      Returns:
      new chronological history with only one cutover from julian to gregorian calendar
      Throws:
      IllegalArgumentException - if given date is before first introduction of gregorian calendar on 1582-10-15
      Since:
      3.0
      See Also:
      ofFirstGregorianReform()

    • of

      public static ChronoHistory of​(Locale locale)

      Determines the (usually approximate) history of gregorian calendar reforms for given locale.

      The actual implementation just falls back to the introduction of gregorian calendar by pope Gregor if a locale is not explicitly mentioned in following table. Later releases of Time4J might refine the implementation for most European countries. In any case, this method does not reflect the absolute historic truth. Various regions in many countries used different rules than the rest. And sometimes historic sources and literature are simply unreliable so this method is just an approach on base of best efforts. In case of doubt, users should prefer to model the concrete history themselves as needed. For any cutover date not supported by this method, users can instead call ofGregorianReform(PlainDate).

      This method does not use the language part of given locale but the country part (ISO-3166), in case of Scotland also the variant part (SCT), in case of Germany the variant part (PREUSSEN or PROTESTANT etc.). In order to create an appropriate locale, use a constructor like new Locale(&quot;en&quot;, &quot;GB&quot;, &quot;SCT&quot;).

      Summary
      RegionLocaleGregorian cutoverNew Year (using estimates)Era preference
      ItalyIT1582-10-15CHRISTMAS_STYLE.until(1583)
      FlorenceIT-FLORENCE1582-10-15MARIA_ANUNCIATA.until(1749)
      PisaIT-PISA1582-10-15CALCULUS_PISANUS.until(1749)
      Republic of VeniceIT-VENICE1582-10-15BEGIN_OF_MARCH.until(1798)
      SpainES1582-10-15 BEGIN_OF_JANUARY.until(1383)
      .and(CHRISTMAS_STYLE.until(1556))      		 HISPANIC (until 1383)
      PortugalPT1582-10-15 BEGIN_OF_JANUARY.until(1422)
      .and(CHRISTMAS_STYLE.until(1556))      		 HISPANIC (until 1422)
      PolandPL1582-10-15
      FranceFR1582-12-20EASTER_STYLE.until(1567)
      HollandNL1583-01-01
      Holy Roman Empire 1)DE1582-10-15CHRISTMAS_STYLE.until(1544)
      BavariaDE-BAYERN1583-10-16CHRISTMAS_STYLE.until(1544)
      PrussiaDE-PREUSSEN1610-09-02CHRISTMAS_STYLE.until(1559)
      Germany (protestant)DE-PROTESTANT1700-03-01CHRISTMAS_STYLE.until(1559)
      AustriaAT1584-01-17
      SwitzerlandCH1584-01-22
      HungariaHU1587-11-01
      DanmarkDK1700-03-01MARIA_ANUNCIATA.until(1623)
      NorwayNO1700-03-01MARIA_ANUNCIATA.until(1623)
      EnglandGB1752-09-14 CHRISTMAS_STYLE.until(1087)
      .and(BEGIN_OF_JANUARY.until(1155))
      .and(MARIA_ANUNCIATA.until(1752))
      ScotlandGB-SCT1752-09-14 CHRISTMAS_STYLE.until(1087)
      .and(BEGIN_OF_JANUARY.until(1155))
      .and(MARIA_ANUNCIATA.until(1600))
      Sweden 2)SE1753-03-01
      Russia 3)RU1918-02-14 BEGIN_OF_JANUARY.until(988)
      .and(BEGIN_OF_MARCH.until(1493))
      .and(BEGIN_OF_SEPTEMBER.until(1700))      		 BYZANTINE (988-1700)

      1) Fallback for catholic regions in German countries, but most regions started Gregorian calendar later.
      2) Sweden used a special calendar shifted by one day between 1700 and 1712 (supported by Time4J).
      3) Special case for Byzantine year 7208: It lasted from AD-1699-09-01 until AD-1699-12-31 (Julian calendar).

      Parameters:
      locale - country setting
      Returns:
      localized chronological history
      Since:
      3.0
      See Also:
      ofGregorianReform(PlainDate)

    • ofSweden

      public static ChronoHistory ofSweden()

      The Swedish calendar has three cutover dates due to a failed experiment when switching to gregorian calendar in the years 1700-1712 step by step.

      Returns:
      swedish chronological history
      Since:
      3.0

    • isValid

      public boolean isValid​(HistoricDate date)

      Is given historic date valid?

      If the argument is null then this method returns false.

      Parameters:
      date - historic calendar date to be checked, maybe null
      Returns:
      false if given date is invalid else true
      Since:
      3.0

    • convert

      public PlainDate convert​(HistoricDate date)

      Converts given historic date to an ISO-8601-date.

      Parameters:
      date - historic calendar date
      Returns:
      ISO-8601-date (gregorian)
      Throws:
      IllegalArgumentException - if given date is invalid or out of supported range
      Since:
      3.0
      See Also:
      isValid(HistoricDate)

    • convert

      public HistoricDate convert​(PlainDate date)

      Converts given ISO-8601-date to a historic date.

      Parameters:
      date - ISO-8601-date (gregorian)
      Returns:
      historic calendar date
      Throws:
      IllegalArgumentException - if given date is out of supported range
      Since:
      3.0

    • from

      public static ChronoHistory from​(String variant)

      Reconstructs the calendar history from given variant description.

      Parameters:
      variant - description as defined in getVariant()
      Returns:
      ChronoHistory
      Throws:
      IllegalArgumentException - if the variant cannot be interpreted as calendar history
      Since:
      3.36/4.31

    • getVariant

      public String getVariant()

      Yields the variant of a historic calendar.

      Specified by:
      getVariant in interface VariantSource
      Returns:
      text describing the internal state
      Since:
      3.11/4.8
      See Also:
      from(String)

    • getGregorianCutOverDate

      public PlainDate getGregorianCutOverDate()

      Yields the date of final introduction of gregorian calendar.

      Returns:
      ISO-8601-date (gregorian)
      Throws:
      UnsupportedOperationException - if this history is proleptic
      Since:
      3.0
      See Also:
      hasGregorianCutOverDate()

    • hasGregorianCutOverDate

      public boolean hasGregorianCutOverDate()

      Determines if this history has at least one gregorian calendar reform date.

      Returns:
      boolean
      Since:
      3.11/4.8
      See Also:
      getGregorianCutOverDate()

    • getBeginOfYear

      public HistoricDate getBeginOfYear​(HistoricEra era, int yearOfEra)

      Determines the date of New Year.

      Side note: This method should usually yield a valid historic date unless in case of ill configured new-year-strategies which don't play well with configured cutover-dates.

      Parameters:
      era - historic era
      yearOfEra - historic year of era as displayed (deviating from standard calendar year)
      Returns:
      historic date of New Year
      Throws:
      IllegalArgumentException - if given year is out of range or such that the result becomes invalid
      Since:
      3.14/4.11
      See Also:
      NewYearRule, getLengthOfYear(HistoricEra, int), with(NewYearStrategy), isValid(HistoricDate), HistoricDate.getYearOfEra(NewYearStrategy)

    • getLengthOfYear

      public int getLengthOfYear​(HistoricEra era, int yearOfEra)

      Determines the length of given historic year in days.

      The length of year can be affected by cutover gaps, different leap year rules and new year strategies.

      Parameters:
      era - historic era
      yearOfEra - historic year of era as displayed (deviating from standard calendar year)
      Returns:
      length of historic year in days or -1 if the length cannot be determined
      Since:
      3.0
      See Also:
      getBeginOfYear(HistoricEra, int), getGregorianCutOverDate(), with(NewYearStrategy), with(AncientJulianLeapYears), HistoricDate.getYearOfEra(NewYearStrategy)

    • getAncientJulianLeapYears

      public AncientJulianLeapYears getAncientJulianLeapYears()

      Yields the historic julian leap year pattern if available.

      Returns:
      sequence of historic julian leap years
      Throws:
      UnsupportedOperationException - if this history has not defined any historic julian leap years
      Since:
      3.11/4.8
      See Also:
      hasAncientJulianLeapYears(), with(AncientJulianLeapYears)

    • hasAncientJulianLeapYears

      public boolean hasAncientJulianLeapYears()

      Determines if this history has defined any historic julian leap year sequence.

      Returns:
      boolean
      Since:
      3.11/4.8
      See Also:
      with(AncientJulianLeapYears), getAncientJulianLeapYears()

    • with

      public ChronoHistory with​(AncientJulianLeapYears ancientJulianLeapYears)

      Creates a copy of this history with given historic julian leap year sequence.

      This method has no effect if applied on ChronoHistory.PROLEPTIC_GREGORIAN or ChronoHistory.PROLEPTIC_JULIAN or ChronoHistory.PROLEPTIC_BYZANTINE.

      Parameters:
      ancientJulianLeapYears - sequence of historic julian leap years
      Returns:
      new history which starts at first of January in year BC 45
      Since:
      3.11/4.8

    • getNewYearStrategy

      public NewYearStrategy getNewYearStrategy()

      Yields the new-year-strategy.

      If not specified then this method falls back to first of January.

      Returns:
      NewYearStrategy
      Since:
      3.14/4.11
      See Also:
      with(NewYearStrategy)

    • with

      public ChronoHistory with​(NewYearStrategy newYearStrategy)

      Creates a copy of this history with given new-year-strategy.

      This method has no effect if applied on ChronoHistory.PROLEPTIC_GREGORIAN or ChronoHistory.PROLEPTIC_JULIAN or ChronoHistory.PROLEPTIC_BYZANTINE.

      Parameters:
      newYearStrategy - strategy how to determine New Year
      Returns:
      new history with changed new-year-strategy
      Since:
      3.14/4.11
      See Also:
      getBeginOfYear(HistoricEra, int), getLengthOfYear(HistoricEra, int), getNewYearStrategy()

    • with

      public ChronoHistory with​(EraPreference eraPreference)

      Creates a copy of this history with given era preference.

      This method has no effect if applied on ChronoHistory.PROLEPTIC_GREGORIAN or ChronoHistory.PROLEPTIC_JULIAN or ChronoHistory.PROLEPTIC_BYZANTINE.

      Background: Some historic calendars used different eras than AD or BC. For example, Russia used the Byzantine calendar before Julian year 1700 using the era Anno Mundi. This can be expressed by setting a suitable era preference.

      Parameters:
      eraPreference - strategy which era should be preferred (most relevant for printing)
      Returns:
      new history with changed era preference
      Since:
      3.14/4.11

    • date

      public ChronoElement<HistoricDate> date()

      Defines the element for the historic date.

      This element is applicable on all chronological types which have registered the element PlainDate.COMPONENT.

      Returns:
      date-related element
      Since:
      3.15/4.12
      See Also:
      PlainDate, PlainTimestamp

    • era

      @FormattableElement(format="G") public ChronoElement<HistoricEra> era()

      Defines the element for the historic era.

      This element is applicable on all chronological types which have registered the element PlainDate.COMPONENT. The era value cannot be changed in any way which makes sense so this element is like a display-only element.

      Returns:
      era-related element
      Since:
      3.0
      See Also:
      PlainDate, PlainTimestamp

    • yearOfEra

      @FormattableElement(format="y") public TextElement<Integer> yearOfEra()

      Defines the element for the year of a given historic era.

      This element is applicable on all chronological types which have registered the element PlainDate.COMPONENT. The year starts on first of January. Note: Getting true historic years which take care of different new-year-rules is possible via the expression plainDate.get(history.date()).getYearOfEra(history.getNewYearStrategy()).

      Returns:
      year-of-era-related element
      Since:
      3.0
      See Also:
      PlainDate, PlainTimestamp, yearOfEra(YearDefinition)

    • yearOfEra

      public ChronoElement<Integer> yearOfEra​(YearDefinition yearDefinition)

      Defines the element for the year of a given historic era.

      This element is applicable on all chronological types which have registered the element PlainDate.COMPONENT.

      Example: Many parts of France used Easter style for New Year so the year 1564 began on 1564-04-01 and ended on 1565-04-21 causing an ambivalency for April dates. Setting the date to April 10th in historic year 1564 can be expressed in a non-ambivalent way if a suitable year definition is applied (standard calendar years 1564 or 1565 possible). 

           ChronoHistory history = ChronoHistory.of(Locale.FRANCE);
     PlainDate date = history.convert(HistoricDate.of(HistoricEra.AD, 1563, 4, 10));
     assertThat(
          date.with(history.yearOfEra(YearDefinition.AFTER_NEW_YEAR), 1564),
          is(history.convert(HistoricDate.of(HistoricEra.AD, 1564, 4, 10))));
     assertThat(
          date.with(history.yearOfEra(YearDefinition.BEFORE_NEW_YEAR), 1564),
          is(history.convert(HistoricDate.of(HistoricEra.AD, 1565, 4, 10))));
      Parameters:
      yearDefinition - determines how to display or interprete a historic year
      Returns:
      year-of-era-related element
      Since:
      3.19/4.15
      See Also:
      PlainDate, PlainTimestamp

    • centuryOfEra

      public ChronoElement<Integer> centuryOfEra()

      Defines the element for the century of a year in a given historic era.

      This element is applicable on all chronological types which have registered the element PlainDate.COMPONENT. The underlying year starts on first of January. As example, the 20th century lasted from year 1901 to year 2000.

      Returns:
      century-of-era-related element
      Since:
      3.23/4.19
      See Also:
      PlainDate, PlainTimestamp, yearOfEra()

    • month

      @FormattableElement(format="M", alt="L") public TextElement<Integer> month()

      Defines the element for the historic month.

      This element is applicable on all chronological types which have registered the element PlainDate.COMPONENT.

      Returns:
      month-related element
      Since:
      3.0
      See Also:
      PlainDate, PlainTimestamp

    • dayOfMonth

      @FormattableElement(format="d") public ChronoElement<Integer> dayOfMonth()

      Defines the element for the historic day of month.

      This element is applicable on all chronological types which have registered the element PlainDate.COMPONENT.

      Returns:
      day-of-month-related element
      Since:
      3.0
      See Also:
      PlainDate, PlainTimestamp

    • dayOfYear

      @FormattableElement(format="D") public ChronoElement<Integer> dayOfYear()

      Defines the element for the historic day of year.

      This element is applicable on all chronological types which have registered the element PlainDate.COMPONENT. Note: An eventually deviating new-year-strategy will be taken into account so this element follows the year cycle which is decoupled from the month cycle.

      Returns:
      day-of-year-related element
      Since:
      3.16/4.13
      See Also:
      PlainDate, PlainTimestamp

    • getElements

      public Set<ChronoElement<?>> getElements()

      Yields all associated elements.

      Returns:
      unmodifiable set of historic elements
      Since:
      3.1

    • equals

      public boolean equals​(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object