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
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.
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.JANUARYexists), 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 aClocktonow(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()andparse()format, so values round-trip without a formatter. - Local types are not moments. A
LocalDateTimecannot be converted to anInstantwithout a zone or offset. - Legacy bridges exist for
Date,Calendarand JDBC; see Converting legacy and modern types.
Related
LocalDate,ZonedDateTime,Instant,DateTimeFormatter- Tutorial: Dates and Times