Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Date and Time

Year, YearMonth and MonthDay

Reference for java.time Year, YearMonth and MonthDay: model partial dates such as card expiry, billing months and birthdays, with leap-year handling.

Not every date has a day, a month and a year. A credit card expires in "03/2028", a report covers "October 2026", and a birthday repeats on "29 February" every year. Three small value classes in java.time model exactly these partial dates:

  • Year is a calendar year (2026).
  • YearMonth is a year and a month with no day.
  • MonthDay is a month and a day with no year.

Using them instead of a LocalDate with a fake "1st of the month" removes a whole class of bugs. All three are immutable, thread-safe and comparable.

Java
YearMonth card = YearMonth.of(2028, 3);
boolean valid = !card.isBefore(YearMonth.of(2026, 10));

Try it

Java YearMonth for billing periods

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Year and MonthDay for leap years and birthdays

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
Year.of(int isoYear)            Year.isLeap(long year)
YearMonth.of(int year, int month)   YearMonth.of(int year, Month month)
MonthDay.of(int month, int dayOfMonth)   MonthDay.of(Month month, int dayOfMonth)
Class Useful members
Year of, now, isLeap(), length() (365 or 366), atDay(int), atMonth(...), plusYears, getValue().
YearMonth of, from(temporal), parse, lengthOfMonth(), lengthOfYear(), atDay(int), atEndOfMonth(), plusMonths, minusMonths, getMonth(), getYear().
MonthDay of, from(temporal), parse, atYear(int), isValidYear(int), getMonth(), getDayOfMonth(), isBefore, isAfter.

Throws: DateTimeException for a month outside 1-12, a day outside the month (YearMonth.atDay(31) in February), or MonthDay.of(2, 30). Parsing failures throw DateTimeParseException.

Usage notes

  • Text forms. toString() gives ISO-8601: 2028-02 for YearMonth, --02-29 for MonthDay, 2028 for Year. Parse the same shapes with parse(text), or supply a formatter for 03/2028.
  • Feb 29 is allowed in MonthDay. MonthDay.of(2, 29) is valid because the class has no year. atYear(2027) adjusts to 28 February in non-leap years.
  • Leap-year rule. A year is leap if divisible by 4, except century years not divisible by 400, so 1900 is not leap and 2000 is. Year.isLeap uses this proleptic Gregorian rule even for dates before 1582.
  • Natural ordering. All three implement Comparable, so they sort and work as TreeMap keys. MonthDay compares by month, then day.
  • Do not build them with the clock in tests. Year.now() and YearMonth.now() read the system clock; pass a Clock to make code testable.
  • Persistence. Store a YearMonth as the text 2028-03 or two integers; do not store it as 2028-03-01, which invites misuse as a day.