javax.time.i18n
Class HistoricDate

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

public final class HistoricDate
extends java.lang.Object
implements Calendrical, java.lang.Comparable<HistoricDate>, java.io.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).

This class is immutable and thread-safe.

Author:
Michael Nascimento Santos, Stephen Colebourne
See Also:
Serialized Form

Field Summary
static int MAX_YEAR
          The maximum valid year of era.
static LocalDate STANDARD_CUTOVER
          The standard cutover date between the Julian and Gregorian calendar system of 1582-10-15.
 
Method Summary
 int compareTo(HistoricDate otherDate)
          Compares this date to the specified date.
 boolean equals(java.lang.Object otherDate)
          Checks is this date is equal to the specified date.
<T> T
get(CalendricalRule<T> ruleToDerive)
          Gets the value of the specified calendrical rule.
 HistoricChronology getChronology()
          Gets the chronology that this date uses, which is the historic calendar system.
 int getDayOfMonth()
          Gets the historic day-of-month value.
 DayOfWeek getDayOfWeek()
          Gets the historic day-of-week.
 int getDayOfYear()
          Gets the historic day-of-year value.
 HistoricEra getEra()
          Gets the historic era.
 MonthOfYear getMonthOfYear()
          Gets the historic month-of-year value.
 int getYear()
          Gets the historic year value, which can be negative.
 int getYearOfEra()
          Gets the historic year-of-era value.
 int hashCode()
          A hash code for this date.
 boolean isAfter(HistoricDate otherDate)
          Checks is this date is after the specified date.
 boolean isBefore(HistoricDate otherDate)
          Checks is this date is before the specified date.
 boolean isLeapYear()
          Checks if the date represented is a leap year.
static HistoricDate of(Calendrical calendrical)
          Obtains an instance of HistoricDate from a calendrical.
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.
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.
 HistoricDate plusDays(int days)
          Returns a copy of this date with the specified number of days added.
 HistoricDate plusMonths(int months)
          Returns a copy of this date with the specified number of months added.
 HistoricDate plusYears(int years)
          Returns a copy of this date with the specified number of years added.
static CalendricalRule<HistoricDate> rule()
          Gets the rule for HistoricDate.
 LocalDate toLocalDate()
          Converts this date to an ISO-8601 calendar system LocalDate.
 java.lang.String toString()
          Outputs the date as a String, such as '1723-13-01 (Historic 2010-10-15)'.
 HistoricDate withDayOfMonth(int dayOfMonth)
          Returns a copy of this date with the day-of-month value altered.
 HistoricDate withDayOfYear(int dayOfYear)
          Returns a copy of this date with the day-of-year value altered.
 HistoricDate withMonthOfYear(MonthOfYear monthOfYear)
          Returns a copy of this date with the month-of-year value altered.
 HistoricDate withYear(int historicYear)
          Returns a copy of this date with the year value altered.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

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:
Constant Field Values
Method Detail

rule

public static CalendricalRule<HistoricDate> rule()
Gets the rule for HistoricDate.

Returns:
the rule for the date, not null

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, not 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, not 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, not null
Throws:
CalendricalException - if the day-of-week cannot be obtained

getChronology

public HistoricChronology getChronology()
Gets the chronology that this date uses, which is the historic calendar system.

Returns:
the historic chronology, not null

get

public <T> T get(CalendricalRule<T> ruleToDerive)
Gets the value of the specified calendrical rule.

This method queries the value of the specified calendrical rule. If the value cannot be returned for the rule from this date then null will be returned.

Specified by:
get in interface Calendrical
Parameters:
ruleToDerive - the rule to derive, not null
Returns:
the value for the rule, null if the value cannot be returned

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, not 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, not 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, not 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, not 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, not 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, not 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, not 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, not 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, not 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, not null
Throws:
IllegalCalendarFieldValueException - if the year range is exceeded

toLocalDate

public LocalDate toLocalDate()
Converts this date to an ISO-8601 calendar system LocalDate.

Returns:
the equivalent date in the ISO-8601 calendar system, not 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 java.lang.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(java.lang.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 java.lang.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 java.lang.Object
Returns:
a suitable hash code

toString

public java.lang.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 java.lang.Object
Returns:
the formatted date string, not null