Package javax.time.calendar

Class Year

java.lang.Object

javax.time.calendar.Year

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<Year>, Calendrical, CalendricalMatcher, DateAdjuster

public final class Year
extends java.lang.Object
implements Calendrical, java.lang.Comparable<Year>, java.io.Serializable, DateAdjuster, CalendricalMatcher

A year in the ISO-8601 calendar system, such as 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:

Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static int	MAX_YEAR	Constant for the maximum year on the proleptic ISO calendar system, 999,999,999.
static int	MIN_YEAR	Constant for the minimum year on the proleptic ISO calendar system, -999,999,999.
private static long	serialVersionUID	A serialization identifier for this class.
private int	year	The year being represented.

Constructor Summary

Constructors

Modifier	Constructor	Description
private	Year(int year)	Constructor.

Method Summary

Modifier and Type	Method	Description
LocalDate	adjustDate(LocalDate date)	Adjusts a date to have the value of this year, returning a new date.
LocalDate	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.
LocalDate	atDay(int dayOfYear)	Returns a date formed from this year at the specified day-of-year.
YearMonth	atMonth(int monthOfYear)	Returns a year-month formed from this year at the specified month.
YearMonth	atMonth(MonthOfYear monthOfYear)	Returns a year-month formed from this year at the specified month.
LocalDate	atMonthDay(MonthDay monthDay)	Returns a date formed from this year at the specified month-day.
int	compareTo(Year other)	Compares this year to another year.
boolean	equals(java.lang.Object other)	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	isAfter(Year other)	Is this year after the specified year.
boolean	isBefore(Year other)	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	lengthInDays()	Gets the length of this year in days.
boolean	matchesCalendrical(Calendrical calendrical)	Checks if the year extracted from the calendrical matches this.
Year	minus(PeriodProvider periodProvider)	Returns a copy of this Year with the specified period subtracted.
Year	minusYears(long years)	Returns a copy of this Year with the specified number of years subtracted.
Year	next()	Returns the next year.
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	now(Clock clock)	Obtains the current year from the specified clock.
static Year	of(int isoYear)	Obtains an instance of Year.
static Year	of(Calendrical calendrical)	Obtains an instance of Year from a calendrical.
Year	plus(PeriodProvider periodProvider)	Returns a copy of this Year with the specified period added.
Year	plusYears(long years)	Returns a copy of this Year with the specified number of years added.
Year	previous()	Returns the previous year.
Year	previousLeap()	Returns the previous leap year before the current year.
static DateTimeFieldRule<java.lang.Integer>	rule()	Gets the rule that defines how the year field operates.
java.lang.String	toString()	Outputs the string form of the year.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

MIN_YEAR

public static final int MIN_YEAR

Constant for the minimum year on the proleptic ISO calendar system, -999,999,999.

See Also:

Constant Field Values

MAX_YEAR

public static final int MAX_YEAR

Constant for the maximum year on the proleptic ISO calendar system, 999,999,999.

See Also:

Constant Field Values

serialVersionUID

private static final long serialVersionUID

A serialization identifier for this class.

See Also:

Constant Field Values

year

private final int year

The year being represented.

Constructor Detail

Year

private Year(int year)

Constructor.

Parameters:

year - the year to represent

Method Detail

rule

public static DateTimeFieldRule<java.lang.Integer> 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

public static Year 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

public static Year now(Clock clock)

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

public static Year of(int isoYear)

Obtains an instance of Year.

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

public static Year of(Calendrical calendrical)

Obtains an instance of Year 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

public <T> T get(CalendricalRule<T> rule)

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 interface Calendrical

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

public Year next()

Returns the next year.

Returns:

the next year, never null

Throws:

CalendricalException - if the maximum year is reached

nextLeap

public Year nextLeap()

Returns the next leap year after the current year. The definition of a leap year is specified in isLeap().

Returns:

the next leap year after this year, never null

Throws:

CalendricalException - if the maximum year is reached

previous

public Year previous()

Returns the previous year.

Returns:

the previous year, never null

Throws:

CalendricalException - if the maximum year is reached

previousLeap

public Year previousLeap()

Returns the previous leap year before the current year. The definition of a leap year is specified in isLeap().

Returns:

the previous leap year after this year, never null

Throws:

CalendricalException - if the minimum year is reached

plus

public Year plus(PeriodProvider periodProvider)

Returns a copy of this Year 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 using Period.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 a Period

java.lang.ArithmeticException - if the result exceeds the supported year range

plusYears

public Year plusYears(long years)

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

public Year minus(PeriodProvider periodProvider)

Returns a copy of this Year 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 using Period.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 a Period

java.lang.ArithmeticException - if the result exceeds the supported year range

minusYears

public Year minusYears(long years)

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

public boolean matchesCalendrical(Calendrical calendrical)

Checks if the year extracted from the calendrical matches this.

This method implements the CalendricalMatcher interface. It is intended that applications use LocalDate.matches(javax.time.calendar.CalendricalMatcher) rather than this method.

Specified by:

matchesCalendrical in interface CalendricalMatcher

Parameters:

calendrical - the calendrical to match, not null

Returns:

true if the calendrical matches, false otherwise

adjustDate

public LocalDate adjustDate(LocalDate date)

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 of LocalDate:

   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 interface DateAdjuster

Parameters:

date - the date to be adjusted, not null

Returns:

the adjusted date, never null

adjustDate

public LocalDate 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.

This instance is immutable and unaffected by this method call.

Parameters:

date - the date to be adjusted, not null

resolver - 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

public boolean isValidMonthDay(MonthDay monthDay)

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

public YearMonth atMonth(MonthOfYear monthOfYear)

Returns a year-month formed from this year at the specified month.

This method merges this and the specified month to form an instance of YearMonth. 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

public YearMonth atMonth(int monthOfYear)

Returns a year-month formed from this year at the specified month.

This method merges this and the specified month to form an instance of YearMonth. 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

public LocalDate atMonthDay(MonthDay monthDay)

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 of LocalDate.

 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

public LocalDate atDay(int dayOfYear)

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 of LocalDate.

 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

public int compareTo(Year other)

Compares this year to another year.

Specified by:

compareTo in interface java.lang.Comparable<Year>

Parameters:

other - the other year to compare to, not null

Returns:

the comparator value, negative if less, positive if greater

Throws:

java.lang.NullPointerException - if other is null

isAfter

public boolean isAfter(Year other)

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:

java.lang.NullPointerException - if other is null

isBefore

public boolean isBefore(Year other)

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:

java.lang.NullPointerException - if other is null

equals

public boolean equals(java.lang.Object other)

Is this year equal to the specified year.

Overrides:

equals in class java.lang.Object

Parameters:

other - the other year to compare to, null returns false

Returns:

true if this point is equal to the specified year

hashCode

public int hashCode()

A hash code for this year.

Overrides:

hashCode in class java.lang.Object

Returns:

a suitable hash code

toString

public java.lang.String toString()

Outputs the string form of the year.

Overrides:

toString in class java.lang.Object

Returns:

the string form of the year