Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Date and Time

The java.time package: an overview

Overview of the java.time API: which class to use for dates, times, time zones, instants and amounts of time, how immutability works, and how they fit together.

The java.time package, added in Java 8, is the standard way to work with dates and times. It replaced Date, Calendar and SimpleDateFormat with a set of small, immutable classes that each represent exactly one idea. Because every object is immutable, every "change" returns a new object, and all the classes are safe to share between threads.

The key to using the package well is choosing the class that matches what your value means. A birthday is a date without a time. A meeting is a date, a time and a place. A log entry is a single moment on the global timeline. A delay is an amount of time. Each has its own type, and the compiler stops you from mixing them up.

Choosing a type

Question Class Example text
Which day, with no time? LocalDate 2025-07-14
Which clock time, with no date? LocalTime 09:30
Which date and clock time, without a zone? LocalDateTime 2025-07-14T09:30
Date and time in a region with its rules? ZonedDateTime 2025-07-14T09:30+02:00[Europe/Paris]
Date and time with a fixed offset? OffsetDateTime 2025-07-14T09:30+02:00
One exact moment on the timeline? Instant 2025-07-14T07:30:00Z
An amount of seconds? Duration PT1H30M
An amount of years, months, days? Period P1Y2M3D

Smaller helpers fill the gaps: Year, YearMonth and MonthDay, the enums DayOfWeek and Month, ZoneId and ZoneOffset, ChronoUnit, TemporalAdjusters, DateTimeFormatter and Clock.

Try it

Java Creating each kind of value

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 Immutability and arithmetic

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.

Package structure

Package Contents
java.time The main value classes (LocalDate, Instant, Duration, ...).
java.time.format DateTimeFormatter, FormatStyle, DateTimeParseException.
java.time.temporal Fields, units and adjusters (ChronoUnit, ChronoField, TemporalAdjusters).
java.time.zone Time-zone rules and transitions.
java.time.chrono Other calendars (Japanese, Thai Buddhist, Hijrah, Minguo, ISO).

Usage notes

  • Immutable. date.plusDays(1) does nothing useful on its own: assign the result.
  • Months are 1 to 12 (and Month.JANUARY exists), days of week are 1 (Monday) to 7 (Sunday). No more zero-based months.
  • Factory methods, not constructors: of(...), parse(...), from(...), now().
  • now() reads the system clock and zone. Tests become fragile; pass a Clock to now(clock).
  • Store instants, show zoned values. Save timestamps as Instant (or UTC in the database) and convert to a zone only for display.
  • ISO-8601 text is the default toString() and parse() format, so values round-trip without a formatter.
  • Local types are not moments. A LocalDateTime cannot be converted to an Instant without a zone or offset.
  • Legacy bridges exist for Date, Calendar and JDBC; see Converting legacy and modern types.