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.

Since:

3.0

Author:

Meno Hochschild

See Also:

Serialized Form

Concurrency:

This class is immutable and can be used by multiple threads in parallel.

Field Summary

Fields

Modifier and Type	Field and Description
static ChronoHistory	PROLEPTIC_BYZANTINE Describes no real historic event but just the proleptic byzantine calendar which is assumed to be in power all times on or after the creation of the world.
static ChronoHistory	PROLEPTIC_GREGORIAN Describes no real historic event but just the proleptic gregorian calendar which is assumed to be in power all times.
static ChronoHistory	PROLEPTIC_JULIAN Describes no real historic event but just the proleptic julian calendar which is assumed to be in power all times.
static AttributeKey<YearDefinition>	YEAR_DEFINITION Format attribute controlling the type of historic year used in parsing or formatting.

Method Summary

Modifier and Type	Method and Description
ChronoElement<Integer>	centuryOfEra() Defines the element for the century of a year in a given historic era.
PlainDate	convert(HistoricDate date) Converts given historic date to an ISO-8601-date.
HistoricDate	convert(PlainDate date) Converts given ISO-8601-date to a historic date.
ChronoElement<HistoricDate>	date() Defines the element for the historic date.
TextElement<Integer>	dayOfMonth() Defines the element for the historic day of month.
TextElement<Integer>	dayOfYear() Defines the element for the historic day of year.
boolean	equals(Object obj)
ChronoElement<HistoricEra>	era() Defines the element for the historic era.
AncientJulianLeapYears	getAncientJulianLeapYears() Yields the historic julian leap year pattern if available.
HistoricDate	getBeginOfYear(HistoricEra era, int yearOfEra) Determines the date of New Year.
Set<ChronoElement<?>>	getElements() Yields all associated elements.
PlainDate	getGregorianCutOverDate() Yields the date of final introduction of gregorian calendar.
int	getLengthOfYear(HistoricEra era, int yearOfEra) Determines the length of given historic year in days.
NewYearStrategy	getNewYearStrategy() Yields the new-year-strategy.
String	getVariant() Yields the variant of a historic calendar.
boolean	hasAncientJulianLeapYears() Determines if this history has defined any historic julian leap year sequence.
boolean	hasGregorianCutOverDate() Determines if this history has at least one gregorian calendar reform date.
int	hashCode()
boolean	isValid(HistoricDate date) Is given historic date valid?
TextElement<Integer>	month() Defines the element for the historic month.
static ChronoHistory	of(Locale locale) Determines the (usually approximate) history of gregorian calendar reforms for given locale.
static ChronoHistory	ofFirstGregorianReform() Describes the original switch from julian to gregorian calendar introduced by pope Gregor on 1582-10-15.
static ChronoHistory	ofGregorianReform(PlainDate start) Describes a single switch from julian to gregorian calendar at given date.
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.
String	toString()
ChronoHistory	with(AncientJulianLeapYears ancientJulianLeapYears) Creates a copy of this history with given historic julian leap year sequence.
ChronoHistory	with(EraPreference eraPreference) Creates a copy of this history with given era preference.
ChronoHistory	with(NewYearStrategy newYearStrategy) Creates a copy of this history with given new-year-strategy.
TextElement<Integer>	yearOfEra() Defines the element for the year of a given historic era.
ChronoElement<Integer>	yearOfEra(YearDefinition yearDefinition) Defines the element for the year of a given historic era.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

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.

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 on or after the creation of the world.

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 Detail

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("en", "GB", "SCT").

Summary

Region	Locale	Gregorian cutover	New Year (using estimates)	Era preference
Italy	IT	1582-10-15	CHRISTMAS_STYLE.until(1583)
Florence	IT-FLORENCE	1582-10-15	MARIA_ANUNCIATA.until(1749)
Pisa	IT-PISA	1582-10-15	CALCULUS_PISANUS.until(1749)
Republic of Venice	IT-VENICE	1582-10-15	BEGIN_OF_MARCH.until(1798)
Spain	ES	1582-10-15	BEGIN_OF_JANUARY.until(1383) .and(CHRISTMAS_STYLE.until(1556))	HISPANIC (until 1383)
Portugal	PT	1582-10-15	BEGIN_OF_JANUARY.until(1422) .and(CHRISTMAS_STYLE.until(1556))	HISPANIC (until 1422)
Poland	PL	1582-10-15
France	FR	1582-12-20	EASTER_STYLE.until(1567)
Holland	NL	1583-01-01
Holy Roman Empire 1)	DE	1582-10-15	CHRISTMAS_STYLE.until(1544)
Bavaria	DE-BAYERN	1583-10-16	CHRISTMAS_STYLE.until(1544)
Prussia	DE-PREUSSEN	1610-09-02	CHRISTMAS_STYLE.until(1559)
Germany (protestant)	DE-PROTESTANT	1700-03-01	CHRISTMAS_STYLE.until(1559)
Austria	AT	1584-01-17
Switzerland	CH	1584-01-22
Hungaria	HU	1587-11-01
Danmark	DK	1700-03-01	MARIA_ANUNCIATA.until(1623)
Norway	NO	1700-03-01	MARIA_ANUNCIATA.until(1623)
England	GB	1752-09-14	CHRISTMAS_STYLE.until(1087) .and(BEGIN_OF_JANUARY.until(1155)) .and(MARIA_ANUNCIATA.until(1752))
Scotland	GB-SCT	1752-09-14	CHRISTMAS_STYLE.until(1087) .and(BEGIN_OF_JANUARY.until(1155)) .and(MARIA_ANUNCIATA.until(1600))
Sweden 2)	SE	1753-03-01
Russia 3)	RU	1918-02-14	BEGIN_OF_JANUARY.until(988) .and(BEGIN_OF_MARCH.until(1493)) .and(BEGIN_OF_SEPTEMBER.until(1700))	BYZANTINE (988-1700)

¹⁾ Fallback for catholic regions in German countries, but most regions started Gregorian calendar later.
²⁾ Sweden used a special calendar shifted by one day between 1700 and 1712 (supported by Time4J).
³⁾ 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

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

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")
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 TextElement<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 TextElement<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