Class Year
- All Implemented Interfaces:
Serializable
,Comparable<Year>
,Calendrical
,CalendricalMatcher
,DateAdjuster
2007
.
Year
is an immutable calendrical that represents a year.
Any field that can be derived from a year can be obtained.
Note that years in the ISO chronology only align with years in the Gregorian-Julian system for modern years. Parts of Russia did not switch to the modern Gregorian/ISO rules until 1920. As such, historical years must be treated with caution.
This class does not store or represent a month, day, time or time-zone.
Thus, for example, the value "2007" can be stored in a Year
.
Years represented by this class follow the ISO-8601 standard and use the proleptic numbering system. Year 1 is preceded by year 0, then by year -1.
The ISO-8601 calendar system is the modern civil calendar system used today
in most of the world. It is equivalent to the proleptic Gregorian calendar
system, in which todays's rules for leap years are applied for all time.
For most applications written today, the ISO-8601 rules are entirely suitable.
Any application that uses historical dates should consider using HistoricDate
.
Year is immutable and thread-safe.
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final int
Constant for the maximum year on the proleptic ISO calendar system, 999,999,999.static final int
Constant for the minimum year on the proleptic ISO calendar system, -999,999,999.private static final long
A serialization identifier for this class.private final int
The year being represented. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionadjustDate
(LocalDate date) Adjusts a date to have the value of this year, returning a new date.adjustDate
(LocalDate date, DateResolver resolver) Adjusts a date to have the value of this year, using a resolver to handle the case when the day-of-month becomes invalid.atDay
(int dayOfYear) Returns a date formed from this year at the specified day-of-year.atMonth
(int monthOfYear) Returns a year-month formed from this year at the specified month.atMonth
(MonthOfYear monthOfYear) Returns a year-month formed from this year at the specified month.atMonthDay
(MonthDay monthDay) Returns a date formed from this year at the specified month-day.int
Compares this year to another year.boolean
Is this year equal to the specified year.<T> T
get
(CalendricalRule<T> rule) Gets the value of the specified calendrical rule.int
getValue()
Gets the year value.int
hashCode()
A hash code for this year.boolean
Is this year after the specified year.boolean
Is this year before the specified year.boolean
isLeap()
Checks if the year is a leap year, according to the ISO proleptic calendar system rules.boolean
isValidMonthDay
(MonthDay monthDay) Checks if the month-day is valid for this year.int
Gets the length of this year in days.boolean
matchesCalendrical
(Calendrical calendrical) Checks if the year extracted from the calendrical matches this.minus
(PeriodProvider periodProvider) Returns a copy of thisYear
with the specified period subtracted.minusYears
(long years) Returns a copy of this Year with the specified number of years subtracted.next()
Returns the next year.nextLeap()
Returns the next leap year after the current year.static Year
now()
Obtains the current year from the system clock in the default time-zone.static Year
Obtains the current year from the specified clock.static Year
of
(int isoYear) Obtains an instance ofYear
.static Year
of
(Calendrical calendrical) Obtains an instance ofYear
from a calendrical.plus
(PeriodProvider periodProvider) Returns a copy of thisYear
with the specified period added.plusYears
(long years) Returns a copy of this Year with the specified number of years added.previous()
Returns the previous year.Returns the previous leap year before the current year.static DateTimeFieldRule
<Integer> rule()
Gets the rule that defines how the year field operates.toString()
Outputs the string form of the year.
-
Field Details
-
MIN_YEAR
public static final int MIN_YEARConstant for the minimum year on the proleptic ISO calendar system, -999,999,999.- See Also:
-
MAX_YEAR
public static final int MAX_YEARConstant for the maximum year on the proleptic ISO calendar system, 999,999,999.- See Also:
-
serialVersionUID
private static final long serialVersionUIDA serialization identifier for this class.- See Also:
-
year
private final int yearThe year being represented.
-
-
Constructor Details
-
Year
private Year(int year) Constructor.- Parameters:
year
- the year to represent
-
-
Method Details
-
rule
Gets the rule that defines how the year field operates.The rule provides access to the minimum and maximum values, and a generic way to access values within a calendrical.
- Returns:
- the year rule, never null
-
now
Obtains the current year from the system clock in the default time-zone.This will query the
system clock
in the default time-zone to obtain the current year.Using this method will prevent the ability to use an alternate clock for testing because the clock is hard-coded.
- Returns:
- the current year using the system clock, never null
-
now
Obtains the current year from the specified clock.This will query the specified clock to obtain the current year. Using this method allows the use of an alternate clock for testing. The alternate clock may be introduced using
dependency injection
.- Parameters:
clock
- the clock to use, not null- Returns:
- the current year, never null
-
of
Obtains an instance ofYear
.This method accepts a year value from the proleptic ISO calendar system.
The year 2AD/CE is represented by 2.
The year 1AD/CE is represented by 1.
The year 1BC/BCE is represented by 0.
The year 2BC/BCE is represented by -1.- Parameters:
isoYear
- the ISO proleptic year to represent, from MIN_YEAR to MAX_YEAR- Returns:
- the created Year, never null
- Throws:
IllegalCalendarFieldValueException
- if the field is invalid
-
of
Obtains an instance ofYear
from a calendrical.This can be used extract the year value directly from any implementation of
Calendrical
, including those in other calendar systems.- Parameters:
calendrical
- the calendrical to extract from, not null- Returns:
- the Year instance, never null
- Throws:
UnsupportedRuleException
- if the year cannot be obtained
-
getValue
public int getValue()Gets the year value.- Returns:
- the year, from MIN_YEAR to MAX_YEAR
-
get
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 instance then
null
will be returned.- Specified by:
get
in interfaceCalendrical
- Parameters:
rule
- the rule to use, not null- Returns:
- the value for the rule, null if the value cannot be returned
-
isLeap
public boolean isLeap()Checks if the year is a leap year, according to the ISO proleptic calendar system rules.This method applies the current rules for leap years across the whole time-line. In general, a year is a leap year if it is divisible by four without remainder. However, years divisible by 100, are not leap years, with the exception of years divisible by 400 which are.
For example, 1904 is a leap year it is divisible by 4. 1900 was not a leap year as it is divisible by 100, however 2000 was a leap year as it is divisible by 400.
The calculation is proleptic - applying the same rules into the far future and far past. This is historically inaccurate, but is correct for the ISO8601 standard.
- Returns:
- true if the year is leap, false otherwise
-
next
Returns the next year.- Returns:
- the next year, never null
- Throws:
CalendricalException
- if the maximum year is reached
-
nextLeap
Returns the next leap year after the current year. The definition of a leap year is specified inisLeap()
.- Returns:
- the next leap year after this year, never null
- Throws:
CalendricalException
- if the maximum year is reached
-
previous
Returns the previous year.- Returns:
- the previous year, never null
- Throws:
CalendricalException
- if the maximum year is reached
-
previousLeap
Returns the previous leap year before the current year. The definition of a leap year is specified inisLeap()
.- Returns:
- the previous leap year after this year, never null
- Throws:
CalendricalException
- if the minimum year is reached
-
plus
Returns a copy of thisYear
with the specified period added.This adds the specified period to this year, returning a new year. Before addition, the period is converted to a
Period
usingPeriod.of(PeriodProvider)
. The calculation simply adds the amount of years from the specified period. ISO fields other than years are ignored.Note that no normalization is performed. Thus, adding 24 months has no effect. To take months into account, the period must be normalized by the caller.
This instance is immutable and unaffected by this method call.
- Parameters:
periodProvider
- the period to add, not null- Returns:
- a
Year
based on this year with the period added, never null - Throws:
CalendricalException
- if the specified period cannot be converted to aPeriod
ArithmeticException
- if the result exceeds the supported year range
-
plusYears
Returns a copy of this Year with the specified number of years added.This instance is immutable and unaffected by this method call.
- Parameters:
years
- the years to add- Returns:
- a
Year
based on this year with the period added, never null - Throws:
CalendricalException
- if the result exceeds the supported year range
-
minus
Returns a copy of thisYear
with the specified period subtracted.This subtracts the specified period from this year, returning a new year. Before subtraction, the period is converted to a
Period
usingPeriod.of(PeriodProvider)
. The calculation simply adds the amount of years from the specified period. ISO fields other than years are ignored.Note that no normalization is performed. Thus, subtracting 24 months has no effect. To take months into account, the period must be normalized by the caller.
This instance is immutable and unaffected by this method call.
- Parameters:
periodProvider
- the period to subtract, not null- Returns:
- a
Year
based on this year with the period subtracted, never null - Throws:
CalendricalException
- if the specified period cannot be converted to aPeriod
ArithmeticException
- if the result exceeds the supported year range
-
minusYears
Returns a copy of this Year with the specified number of years subtracted.This instance is immutable and unaffected by this method call.
- Parameters:
years
- the years to subtract- Returns:
- a
Year
based on this year with the period subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported year range
-
matchesCalendrical
Checks if the year extracted from the calendrical matches this.This method implements the
CalendricalMatcher
interface. It is intended that applications useLocalDate.matches(javax.time.calendar.CalendricalMatcher)
rather than this method.- Specified by:
matchesCalendrical
in interfaceCalendricalMatcher
- Parameters:
calendrical
- the calendrical to match, not null- Returns:
- true if the calendrical matches, false otherwise
-
adjustDate
Adjusts a date to have the value of this year, returning a new date.This method implements the
DateAdjuster
interface. It is intended that, instead of calling this method directly, it is used from an instance ofLocalDate
:date = date.with(year);
This implementation handles the case where the date represents February 29 and this is not a leap year using the
DateResolvers.previousValid()
resolver.This instance is immutable and unaffected by this method call.
- Specified by:
adjustDate
in interfaceDateAdjuster
- Parameters:
date
- the date to be adjusted, not null- Returns:
- the adjusted date, never null
-
adjustDate
Adjusts a date to have the value of this year, using a resolver to handle the case when the day-of-month becomes invalid.This instance is immutable and unaffected by this method call.
- Parameters:
date
- the date to be adjusted, not nullresolver
- the date resolver to use if the day-of-month becomes invalid, not null- Returns:
- the adjusted date, never null
- Throws:
IllegalCalendarFieldValueException
- if the date cannot be resolved using the resolver
-
lengthInDays
public int lengthInDays()Gets the length of this year in days.- Returns:
- the length of this year in days, 365 or 366
-
isValidMonthDay
Checks if the month-day is valid for this year.This method checks whether this year and the input month and day form a valid date.
- Parameters:
monthDay
- the month-day to validate, null returns false- Returns:
- true if the month and day are valid for this year
-
atMonth
Returns a year-month formed from this year at the specified month.This method merges
this
and the specified month to form an instance ofYearMonth
. This method can be used as part of a chain to produce a date:LocalDate date = year.atMonth(month).atDay(day);
This instance is immutable and unaffected by this method call.
- Parameters:
monthOfYear
- the month-of-year to use, not null- Returns:
- the year-month formed from this year and the specified month, never null
-
atMonth
Returns a year-month formed from this year at the specified month.This method merges
this
and the specified month to form an instance ofYearMonth
. This method can be used as part of a chain to produce a date:LocalDate date = year.atMonth(month).atDay(day);
This instance is immutable and unaffected by this method call.
- Parameters:
monthOfYear
- the month-of-year to use, from 1 (January) to 12 (December)- Returns:
- the year-month formed from this year and the specified month, never null
-
atMonthDay
Returns a date formed from this year at the specified month-day.This merges the two objects -
this
and the specified day - to form an instance ofLocalDate
.LocalDate date = year.atMonthDay(monthDay);
This instance is immutable and unaffected by this method call.
- Parameters:
monthDay
- the month-day to use, not null- Returns:
- the local date formed from this year and the specified month-day, never null
- Throws:
InvalidCalendarFieldException
- if the month-day is February 29th and this is not a leap year
-
atDay
Returns a date formed from this year at the specified day-of-year.This merges the two objects -
this
and the specified day - to form an instance ofLocalDate
.LocalDate date = year.atDay(dayOfYear);
This instance is immutable and unaffected by this method call.
- Parameters:
dayOfYear
- the day-of-year to use, not null- Returns:
- the local date formed from this year and the specified date of year, never null
- Throws:
InvalidCalendarFieldException
- if the day of year is 366 and this is not a leap year
-
compareTo
Compares this year to another year.- Specified by:
compareTo
in interfaceComparable<Year>
- Parameters:
other
- the other year to compare to, not null- Returns:
- the comparator value, negative if less, positive if greater
- Throws:
NullPointerException
- ifother
is null
-
isAfter
Is this year after the specified year.- Parameters:
other
- the other year to compare to, not null- Returns:
- true if this is after the specified year
- Throws:
NullPointerException
- ifother
is null
-
isBefore
Is this year before the specified year.- Parameters:
other
- the other year to compare to, not null- Returns:
- true if this point is before the specified year
- Throws:
NullPointerException
- ifother
is null
-
equals
Is this year equal to the specified year. -
hashCode
public int hashCode()A hash code for this year. -
toString
Outputs the string form of the year.
-