Class HistoricDate

java.lang.Object
javax.time.i18n.HistoricDate
All Implemented Interfaces:
Serializable, Comparable<HistoricDate>, Calendrical, DateProvider

public final class HistoricDate extends Object implements DateProvider, Calendrical, Comparable<HistoricDate>, Serializable
A date in the Historic calendar system.

HistoricDate is an immutable class that represents a date in the Historic calendar system. The rules of the calendar system are described in HistoricChronology. The date has a precision of one day and a range within the era from year 1 to year 999,999,999 (inclusive).

Instances of this class may be created from any other object that implements DateProvider including LocalDate. Similarly, instances of this class may be passed into the factory method of any other implementation of DateProvider.

HistoricDate is immutable and thread-safe.

See Also:
  • Field Details

    • STANDARD_CUTOVER

      public static final LocalDate STANDARD_CUTOVER
      The standard cutover date between the Julian and Gregorian calendar system of 1582-10-15.
    • MAX_YEAR

      public static final int MAX_YEAR
      The maximum valid year of era. This is currently set to 999,999,999 but may be changed to increase the valid range in a future version of the specification.
      See Also:
    • serialVersionUID

      private static final long serialVersionUID
      A serialization identifier for this class.
      See Also:
    • chrono

      private final HistoricChronology chrono
      The cutover between the Julian and Gregorian calendar systems.
    • year

      private final transient int year
      The historic year.
    • month

      private final transient MonthOfYear month
      The historic month.
    • day

      private final transient int day
      The historic day-of-month.
  • Constructor Details

    • HistoricDate

      HistoricDate(HistoricChronology chrono, int year, MonthOfYear month, int day)
      Constructs an instance with the specified date.
      Parameters:
      chono - the chronology, not null
      year - the year to represent, valid
      month - the month-of-year to represent, not null
      day - the day-of-month to represent, valid
  • Method Details

    • of

      public static HistoricDate of(int historicYear, MonthOfYear monthOfYear, int dayOfMonth)
      Obtains an instance of LocalDate from a year, month and day using the standard cutover of 1582-10-15.

      The day must be valid for the year and month or an exception will be thrown.

      Parameters:
      historicYear - the year to represent, from -(MAX_YEAR-1) to MAX_YEAR
      monthOfYear - the month-of-year to represent, not null
      dayOfMonth - the day-of-month to represent, from 1 to 31
      Returns:
      the local date, never null
      Throws:
      IllegalCalendarFieldValueException - if the value of any field is out of range
      InvalidCalendarFieldException - if the day-of-month is invalid for the month-year
    • of

      public static HistoricDate of(LocalDate cutover, int historicYear, MonthOfYear monthOfYear, int dayOfMonth)
      Obtains an instance of LocalDate from a year, month and day specifying the cutover date to use.

      The day must be valid for the year and month or an exception will be thrown.

      Parameters:
      historicYear - the year to represent, from -(MAX_YEAR-1) to MAX_YEAR
      monthOfYear - the month-of-year to represent, not null
      dayOfMonth - the day-of-month to represent, from 1 to 31
      Returns:
      the local date, never null
      Throws:
      IllegalCalendarFieldValueException - if the value of any field is out of range
      InvalidCalendarFieldException - if the day-of-month is invalid for the month-year
    • of

      public static HistoricDate of(Calendrical calendrical)
      Obtains an instance of HistoricDate from a calendrical.

      This can be used extract the date directly from any implementation of Calendrical, including those in other calendar systems.

      Parameters:
      calendrical - the calendrical to extract from, not null
      Returns:
      the Historic date, never null
      Throws:
      UnsupportedRuleException - if the day-of-week cannot be obtained
    • previousValid

      private HistoricDate previousValid(int historicYear, MonthOfYear monthOfYear, int dayOfMonth)
      Obtains an instance of HistoricDate using the previous valid algorithm.
      Parameters:
      historicYear - the year to represent
      monthOfYear - the month-of-year to represent, not null
      dayOfMonth - the day-of-month to represent, from 1 to 31
      Returns:
      the historic date, never null
    • getChronology

      public HistoricChronology getChronology()
      Gets the chronology that this date uses, which is the historic calendar system.
      Returns:
      the historic chronology, never null
    • get

      public <T> T get(CalendricalRule<T> rule)
      Gets the value of the specified calendar field.

      This method queries the value of the specified calendar field. If the calendar field is not supported then an exception is thrown.

      Specified by:
      get in interface Calendrical
      Parameters:
      rule - the field to query, not null
      Returns:
      the value for the field
      Throws:
      UnsupportedRuleException - if no value for the field is found
    • getEra

      public HistoricEra getEra()
      Gets the historic era.

      The era provides a context for the year-of-era. This calendar system defines two eras, BCE and CE.

      Returns:
      the era, never null
    • getYearOfEra

      public int getYearOfEra()
      Gets the historic year-of-era value.

      The year-of-era is a value that matches the historic definition. Thus, both 1 AD and 1 BCE are represented as year-of-era 1.

      Returns:
      the year, from 1 to MAX_YEAR
    • getYear

      public int getYear()
      Gets the historic year value, which can be negative.

      The year is value that is continuous. Thus, 1 AD is represented as year 1, and 1 BCE is represented as year 0.

      Returns:
      the year, from -(MAX_YEAR-1) to MAX_YEAR
    • getMonthOfYear

      public MonthOfYear getMonthOfYear()
      Gets the historic month-of-year value.
      Returns:
      the month-of-year, never null
    • getDayOfMonth

      public int getDayOfMonth()
      Gets the historic day-of-month value.
      Returns:
      the day-of-month, from 1 to 30
    • getDayOfYear

      public int getDayOfYear()
      Gets the historic day-of-year value.
      Returns:
      the day-of-year, from 1 to 366
    • getDayOfWeek

      public DayOfWeek getDayOfWeek()
      Gets the historic day-of-week.
      Returns:
      the day-of-week, never null
    • isLeapYear

      public boolean isLeapYear()
      Checks if the date represented is a leap year.
      Returns:
      true if this date is in a leap year
    • withYear

      public HistoricDate withYear(int historicYear)
      Returns a copy of this date with the year value altered.

      The result of setting the year may leave the day-of-month invalid. To avoid this, the day-of-month is changed to the largest valid value.

      This instance is immutable and unaffected by this method call.

      Parameters:
      historicYear - the year to represent, from MIN_YEAR to MAX_YEAR
      Returns:
      a HistoricDate based on this date with the specified year, never null
      Throws:
      IllegalCalendarFieldValueException - if the year is out of range
    • withMonthOfYear

      public HistoricDate withMonthOfYear(MonthOfYear monthOfYear)
      Returns a copy of this date with the month-of-year value altered.

      The result of setting the month may leave the day-of-month invalid. To avoid this, the day-of-month is changed to the largest valid value.

      This instance is immutable and unaffected by this method call.

      Parameters:
      monthOfYear - the month-of-year to represent, from 1 to 12
      Returns:
      a HistoricDate based on this date with the specified month, never null
    • withDayOfMonth

      public HistoricDate withDayOfMonth(int dayOfMonth)
      Returns a copy of this date with the day-of-month value altered.

      The specified day-of-month must be valid for the month and year.

      This instance is immutable and unaffected by this method call.

      Parameters:
      dayOfMonth - the day-of-month to represent, from 1 to 31
      Returns:
      a HistoricDate based on this date with the specified day, never null
      Throws:
      IllegalCalendarFieldValueException - if the day is out of range
      InvalidCalendarFieldException - if the day-of-month is invalid for the year and month
    • withDayOfYear

      public HistoricDate withDayOfYear(int dayOfYear)
      Returns a copy of this date with the day-of-year value altered.

      This instance is immutable and unaffected by this method call.

      Parameters:
      dayOfYear - the day-of-year to represent, from 1 to 366
      Returns:
      a HistoricDate based on this date with the specified day, never null
      Throws:
      IllegalCalendarFieldValueException - if the day-of-year is out of range
      InvalidCalendarFieldException - if the day-of-year is invalid for the year
    • plusYears

      public HistoricDate plusYears(int years)
      Returns a copy of this date with the specified number of years added.

      The result of changing the year may leave the day-of-month invalid. To avoid this, the day-of-month is changed to the largest valid value.

      This instance is immutable and unaffected by this method call.

      Parameters:
      years - the years to add, positive or negative
      Returns:
      a HistoricDate based on this date with the specified years added, never null
      Throws:
      IllegalCalendarFieldValueException - if the year range is exceeded
    • plusMonths

      public HistoricDate plusMonths(int months)
      Returns a copy of this date with the specified number of months added.

      The result of changing the month may leave the day-of-month invalid. To avoid this, the day-of-month is changed to the largest valid value.

      This instance is immutable and unaffected by this method call.

      Parameters:
      months - the months to add, positive or negative
      Returns:
      a HistoricDate based on this date with the specified months added, never null
      Throws:
      IllegalCalendarFieldValueException - if the year range is exceeded
    • plusDays

      public HistoricDate plusDays(int days)
      Returns a copy of this date with the specified number of days added.

      This instance is immutable and unaffected by this method call.

      Parameters:
      days - the days to add, positive or negative
      Returns:
      a HistoricDate based on this date with the specified days added, never null
      Throws:
      IllegalCalendarFieldValueException - if the year range is exceeded
    • toLocalDate

      public LocalDate toLocalDate()
      Converts this date to an ISO-8601 calendar system LocalDate.
      Specified by:
      toLocalDate in interface DateProvider
      Returns:
      the equivalent date in the ISO-8601 calendar system, never null
    • compareTo

      public int compareTo(HistoricDate otherDate)
      Compares this date to the specified date.

      The comparison is based on the year, month, day and cutover date.

      Specified by:
      compareTo in interface Comparable<HistoricDate>
      Parameters:
      otherDate - the other date instance to compare to, not null
      Returns:
      the comparator value, negative if less, positive if greater
    • isAfter

      public boolean isAfter(HistoricDate otherDate)
      Checks is this date is after the specified date.

      The comparison is based on the year, month, day and cutover date.

      Parameters:
      otherDate - the other date instance to compare to, not null
      Returns:
      true if this day is after the specified day
    • isBefore

      public boolean isBefore(HistoricDate otherDate)
      Checks is this date is before the specified date.

      The comparison is based on the year, month, day and cutover date.

      Parameters:
      otherDate - the other date instance to compare to, not null
      Returns:
      true if this day is before the specified day
    • equals

      public boolean equals(Object otherDate)
      Checks is this date is equal to the specified date.

      The comparison is based on the year, month, day and cutover date.

      Overrides:
      equals in class Object
      Parameters:
      otherDate - the other date instance to compare to, null returns false
      Returns:
      true if this day is equal to the specified day
    • hashCode

      public int hashCode()
      A hash code for this date.
      Overrides:
      hashCode in class Object
      Returns:
      a suitable hash code
    • toString

      public String toString()
      Outputs the date as a String, such as '1723-13-01 (Historic 2010-10-15)'.

      The output will be in the format 'yyyy-MM-dd (Historic 2010-10-15)' where 2010-10-15 is the cutover date.

      Overrides:
      toString in class Object
      Returns:
      the formatted date string, never null
    • rule

      public static CalendricalRule<HistoricDate> rule()
      Gets the field rule for HistoricDate.
      Returns:
      the field rule for the date, never null