Java : Basics of Date and Time

Last Modified : May 13, 2023 Published : January 16, 2023

日本語

Java 8 added new APIs of dates and times to the java.time package. This article provides the basics of new APIs, e.g. LocalDate, LocalTime, ZonedDateTime, Instant etc.

Date and Time APIs

There are Date and Time APIs in the java.time package. The APIs mainly used are shown in the table.

final var date = LocalDate.of(2100, 5, 1);
System.out.println(date); // 2100-05-01

System.out.println(date.getYear()); // 2100
System.out.println(date.getMonth()); // MAY
System.out.println(date.getDayOfMonth()); // 1

final var time = LocalTime.of(12, 30, 45);
System.out.println(time); // 12:30:45

System.out.println(time.getHour()); // 12
System.out.println(time.getMinute()); // 30
System.out.println(time.getSecond()); // 45

final var dateTime = LocalDateTime.of(2100, 5, 1, 12, 30, 45);
System.out.println(dateTime); // 2100-05-01T12:30:45

System.out.println(dateTime.getYear()); // 2100
System.out.println(dateTime.getMonth()); // MAY
System.out.println(dateTime.getDayOfMonth()); // 1

System.out.println(dateTime.getHour()); // 12
System.out.println(dateTime.getMinute()); // 30
System.out.println(dateTime.getSecond()); // 45

final var zoneId = ZoneId.systemDefault();
System.out.println(zoneId); // America/Los_Angeles

final var zoneId = ZoneId.systemDefault();
final var dateTime = ZonedDateTime.of(2100, 5, 1, 12, 30, 45, 0, zoneId);
System.out.println(dateTime); // 2100-05-01T12:30:45-07:00[America/Los_Angeles]

System.out.println(dateTime.getYear()); // 2100
System.out.println(dateTime.getMonth()); // MAY
System.out.println(dateTime.getDayOfMonth()); // 1

System.out.println(dateTime.getHour()); // 12
System.out.println(dateTime.getMinute()); // 30
System.out.println(dateTime.getSecond()); // 45
System.out.println(dateTime.getNano()); // 0

System.out.println(dateTime.getZone()); // America/Los_Angeles

final var instant = Instant.ofEpochSecond(4102444800L);
System.out.println(instant); // 2100-01-01T00:00:00Z

System.out.println(instant.getEpochSecond()); // 4102444800
System.out.println(instant.getNano()); // 0

Common features

Immutable objects

The APIs in java.time package are immutable objects. It's also thread-safe.

You may think that it is inconvenient if the value cannot be changed. It's okay. There are with... methods for indirectly modifying :

• withYear
• withMonth
• withHour
• withMinute
• etc.

final var date = LocalDate.of(2100, 1, 1);
System.out.println(date); // 2100-01-01

final var ret1 = date.withYear(2999);
System.out.println(ret1); // 2999-01-01

final var ret2 = date.withMonth(8);
System.out.println(ret2); // 2100-08-01

This article is about the basics of Date and Time, so omits the detailed benefits of immutable objects.

ISO 8601

The string representation of Date and Time APIs is ISO 8601 in the extended format. For example, a result of the toString method is ISO 8601. ISO 8601 can be found in various programming languages, so it's worth understanding.

LocalDate

LocalDate is a date without a time-zone, e.g. 2100-12-03, 1999-05-01 etc. You can also get the day-of-week.

The of method obtains a LocaleDate object.

final var date = LocalDate.of(2100, 5, 1);
System.out.println(date); // 2100-05-01

System.out.println(date.getYear()); // 2100
System.out.println(date.getMonth()); // MAY
System.out.println(date.getDayOfMonth()); // 1

final var date1 = LocalDate.of(2100, 5, 2);
System.out.println(date1); // 2100-05-02
System.out.println(date1.getDayOfWeek()); // SUNDAY

final var date2 = LocalDate.of(2100, 5, 3);
System.out.println(date2); // 2100-05-03
System.out.println(date2.getDayOfWeek()); // MONDAY

final var date3 = LocalDate.of(2100, 5, 4);
System.out.println(date3); // 2100-05-04
System.out.println(date3.getDayOfWeek()); // TUESDAY

The now method obtains a current date.

final var now = LocalDate.now();
System.out.println(now); // 2023-01-14

The format method uses the DateTimeFormatter class to convert an object to a string.

final var date = LocalDate.of(2100, 5, 1);

final var str1 = date.format(DateTimeFormatter.ISO_LOCAL_DATE);
System.out.println(str1); // 2100-05-01

final var str2 = date.format(DateTimeFormatter.ofPattern("MM/dd/yyyy"));
System.out.println(str2); // 05/01/2100

final var str3 = date.format(DateTimeFormatter.ofLocalizedDate(FormatStyle.FULL));
System.out.println(str3); // Saturday, May 1, 2100

The with... methods return a copy with the specified value altered. These methods can be used as an alternative to setters.

final var date = LocalDate.of(2100, 5, 1);
System.out.println(date); // 2100-05-01

final var ret1 = date.withYear(2999);
System.out.println(ret1); // 2999-05-01

final var ret2 = date.withMonth(12);
System.out.println(ret2); // 2100-12-01

final var ret3 = date.withDayOfMonth(31);
System.out.println(ret3); // 2100-05-31

The plus... methods return a copy with the specified amount added. The minus... methods are for subtraction.

final var date = LocalDate.of(2100, 5, 1);
System.out.println(date); // 2100-05-01

final var ret1 = date.plusYears(6);
System.out.println(ret1); // 2106-05-01

final var ret2 = date.minusMonths(3);
System.out.println(ret2); // 2100-02-01

final var ret3 = date.plusDays(50);
System.out.println(ret3); // 2100-06-20

LocalTime

LocalTime is a time without a time-zone, e.g. 10:15:30, 13:45.30.123456789 etc.

The of method obtains a LocalTime object.

final var time = LocalTime.of(18, 30, 45);
System.out.println(time); // 18:30:45

System.out.println(time.getHour()); // 18
System.out.println(time.getMinute()); // 30
System.out.println(time.getSecond()); // 45

The now method obtains a current time.

final var now = LocalTime.now();
System.out.println(now); // 16:54:02.676090600

The format method uses the DateTimeFormatter class to convert an object to a string.

final var time = LocalTime.of(18, 30, 45);

final var str1 = time.format(DateTimeFormatter.ISO_LOCAL_TIME);
System.out.println(str1); // 18:30:45

final var str2 = time.format(DateTimeFormatter.ofPattern("HH:mm:ss"));
System.out.println(str2); // 18:30:45

final var str3 = time.format(DateTimeFormatter.ofLocalizedTime(FormatStyle.MEDIUM));
System.out.println(str3); // 6:30:45 PM

The with... methods return a copy with the specified value altered. These methods can be used as an alternative to setters.

final var time = LocalTime.of(18, 30, 45);
System.out.println(time); // 18:30:45

final var ret1 = time.withHour(9);
System.out.println(ret1); // 09:30:45

final var ret2 = time.withMinute(15);
System.out.println(ret2); // 18:15:45

final var ret3 = time.withSecond(0);
System.out.println(ret3); // 18:30

The plus... methods return a copy with the specified amount added. The minus... methods are for subtraction.

final var time = LocalTime.of(18, 30, 45);
System.out.println(time); // 18:30:45

final var ret1 = time.plusHours(2);
System.out.println(ret1); // 20:30:45

final var ret2 = time.minusMinutes(10);
System.out.println(ret2); // 18:20:45

final var ret3 = time.plusSeconds(100);
System.out.println(ret3); // 18:32:25

LocalDateTime

LocalDateTime is a date-time without a time-zone, e.g. 2100-05-01T18:30:45, 1900-12-03T10:15:30 etc.

The of method obtains a LocalDateTime object.

final var dateTime = LocalDateTime.of(2100, 5, 1, 18, 30, 45);
System.out.println(dateTime); // 2100-05-01T18:30:45

System.out.println(dateTime.getYear()); // 2100
System.out.println(dateTime.getMonth()); // MAY
System.out.println(dateTime.getDayOfMonth()); // 1

System.out.println(dateTime.getHour()); // 18
System.out.println(dateTime.getMinute()); // 30
System.out.println(dateTime.getSecond()); // 45

final var date = LocalDate.of(2100, 5, 1);
final var time = LocalTime.of(18, 30, 45);

final var dateTime = LocalDateTime.of(date, time);
System.out.println(dateTime); // 2100-05-01T18:30:45

The now method obtains a current date-time.

final var now = LocalDateTime.now();
System.out.println(now); // 2023-01-15T15:06:55.081933400

The format method uses the DateTimeFormatter class to convert an object to a string.

final var dateTime = LocalDateTime.of(2100, 5, 1, 18, 30, 45);

final var str1 = dateTime.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
System.out.println(str1); // 2100-05-01T18:30:45

final var str2 = dateTime.format(DateTimeFormatter.ofPattern("MM/dd/yyyy, HH:mm:ss"));
System.out.println(str2); // 05/01/2100, 18:30:45

final var str3 = dateTime.format(DateTimeFormatter.ofLocalizedDateTime(FormatStyle.MEDIUM));
System.out.println(str3); // May 1, 2100, 6:30:45 PM

The with... methods return a copy with the specified value altered. These methods can be used as an alternative to setters.

final var dateTime = LocalDateTime.of(2100, 5, 1, 18, 30, 45);
System.out.println(dateTime); // 2100-05-01T18:30:45

final var ret1 = dateTime.withYear(2999);
System.out.println(ret1); // 2999-05-01T18:30:45

final var ret2 = dateTime.withMonth(12);
System.out.println(ret2); // 2100-12-01T18:30:45

final var ret3 = dateTime.withDayOfMonth(31);
System.out.println(ret3); // 2100-05-31T18:30:45

final var ret4 = dateTime.withHour(9);
System.out.println(ret4); // 2100-05-01T09:30:45

final var ret5 = dateTime.withMinute(15);
System.out.println(ret5); // 2100-05-01T18:15:45

final var ret6 = dateTime.withSecond(0);
System.out.println(ret6); // 2100-05-01T18:30

The plus... methods return a copy with the specified amount added. The minus... methods are for subtraction.

final var dateTime = LocalDateTime.of(2100, 5, 1, 18, 30, 45);
System.out.println(dateTime); // 2100-05-01T18:30:45

final var ret1 = dateTime.plusYears(5);
System.out.println(ret1); // 2105-05-01T18:30:45

final var ret2 = dateTime.minusMonths(3);
System.out.println(ret2); // 2100-02-01T18:30:45

final var ret3 = dateTime.plusDays(50);
System.out.println(ret3); // 2100-06-20T18:30:45

final var ret4 = dateTime.plusHours(2);
System.out.println(ret4); // 2100-05-01T20:30:45

final var ret5 = dateTime.minusMinutes(10);
System.out.println(ret5); // 2100-05-01T18:20:45

final var ret6 = dateTime.plusSeconds(100);
System.out.println(ret6); // 2100-05-01T18:32:25

ZoneId

ZoneId is a time-zone ID.

The of method obtains a ZoneId object from a time-zone ID. You can also use the short time-zone names.

final var zoneId1 = ZoneId.of("America/Los_Angeles");
System.out.println(zoneId1); // America/Los_Angeles

final var zoneId2 = ZoneId.of("PST", ZoneId.SHORT_IDS);
System.out.println(zoneId2); // America/Los_Angeles

The systemDefault method obtains a system default time-zone.

final var zoneId = ZoneId.systemDefault();
System.out.println(zoneId); // America/Los_Angeles

The ZoneOffset.UTC is Coordinated Universal Time(UTC). The ZoneOffset class is a subclass of the ZoneID class.

final var utc = ZoneOffset.UTC;
System.out.println(utc); // Z

ZonedDateTime

ZonedDateTime is a date-time with a time-zone, e.g. 2100-05-01T18:30:45-07:00[America/Los_Angeles], 1900-12-03T10:15:30Z etc.

The of method obtains a ZonedDateTime object.

final var zoneId = ZoneId.systemDefault();
System.out.println(zoneId); // America/Los_Angeles

final var dateTime = ZonedDateTime.of(2100, 5, 1, 18, 30, 45, 0, zoneId);
System.out.println(dateTime); // 2100-05-01T18:30:45-07:00[America/Los_Angeles]

System.out.println(dateTime.getYear()); // 2100
System.out.println(dateTime.getMonth()); // MAY
System.out.println(dateTime.getDayOfMonth()); // 1

System.out.println(dateTime.getHour()); // 18
System.out.println(dateTime.getMinute()); // 30
System.out.println(dateTime.getSecond()); // 45
System.out.println(dateTime.getNano()); // 0

System.out.println(dateTime.getZone()); // America/Los_Angeles

final var utc = ZoneOffset.UTC;
System.out.println(utc); // Z

final var date = LocalDate.of(2100, 5, 1);
final var time = LocalTime.of(18, 30, 45);

final var dateTime = ZonedDateTime.of(date, time, utc);
System.out.println(dateTime); // 2100-05-01T18:30:45Z

The now method obtains a current date-time.

final var now = ZonedDateTime.now();
System.out.println(now); // 2023-01-14T23:13:01.977877100-08:00[America/Los_Angeles]

The format method uses the DateTimeFormatter class to convert an object to a string.

final var dateTime = ZonedDateTime.of(2100, 5, 1, 18, 30, 45, 0, ZoneId.systemDefault());

final var str1 = dateTime.format(DateTimeFormatter.ISO_ZONED_DATE_TIME);
System.out.println(str1); // 2100-05-01T18:30:45-07:00[America/Los_Angeles]

final var str2 = dateTime.format(DateTimeFormatter.ofPattern("MM/dd/yyyy, HH:mm:ss v"));
System.out.println(str2); // 05/01/2100, 18:30:45 PT

final var str3 = dateTime.format(DateTimeFormatter.ofLocalizedDateTime(FormatStyle.FULL));
System.out.println(str3); // Saturday, May 1, 2100 at 6:30:45 PM Pacific Daylight Time

The with... methods return a copy with the specified value altered. These methods can be used as an alternative to setters.

final var zoneId = ZoneId.systemDefault();
System.out.println(zoneId); // America/Los_Angeles

final var dateTime = ZonedDateTime.of(2100, 5, 1, 18, 30, 45, 0, zoneId);
System.out.println(dateTime); // 2100-05-01T18:30:45-07:00[America/Los_Angeles]

final var ret1 = dateTime.withYear(2999);
System.out.println(ret1); // 2999-05-01T18:30:45-07:00[America/Los_Angeles]

final var ret2 = dateTime.withMonth(12);
System.out.println(ret2); // 2100-12-01T18:30:45-08:00[America/Los_Angeles]

final var ret3 = dateTime.withDayOfMonth(31);
System.out.println(ret3); // 2100-05-31T18:30:45-07:00[America/Los_Angeles]

final var ret4 = dateTime.withHour(9);
System.out.println(ret4); // 2100-05-01T09:30:45-07:00[America/Los_Angeles]

final var ret5 = dateTime.withMinute(15);
System.out.println(ret5); // 2100-05-01T18:15:45-07:00[America/Los_Angeles]

final var ret6 = dateTime.withSecond(0);
System.out.println(ret6); // 2100-05-01T18:30-07:00[America/Los_Angeles]

The plus... methods return a copy with the specified amount added. The minus... methods are for subtraction.

final var zoneId = ZoneId.systemDefault();
System.out.println(zoneId); // America/Los_Angeles

final var dateTime = ZonedDateTime.of(2100, 5, 1, 18, 30, 45, 0, zoneId);
System.out.println(dateTime); // 2100-05-01T18:30:45-07:00[America/Los_Angeles]

final var ret1 = dateTime.plusYears(5);
System.out.println(ret1); // 2105-05-01T18:30:45-07:00[America/Los_Angeles]

final var ret2 = dateTime.minusMonths(3);
System.out.println(ret2); // 2100-02-01T18:30:45-08:00[America/Los_Angeles]

final var ret3 = dateTime.plusDays(50);
System.out.println(ret3); // 2100-06-20T18:30:45-07:00[America/Los_Angeles]

final var ret4 = dateTime.plusHours(2);
System.out.println(ret4); // 2100-05-01T20:30:45-07:00[America/Los_Angeles]

final var ret5 = dateTime.minusMinutes(10);
System.out.println(ret5); // 2100-05-01T18:20:45-07:00[America/Los_Angeles]

final var ret6 = dateTime.plusSeconds(100);
System.out.println(ret6); // 2100-05-01T18:32:25-07:00[America/Los_Angeles]

Instant

Instant is an instantaneous point on the time-line. This class has epoch-seconds and nanosecond-of-seconds. The epoch-seconds are measured from the standard Java epoch of 1970-01-01T00:00:00Z.

The ofEpochSecond method obtains an Instant object.

final var instant = Instant.ofEpochSecond(0);
System.out.println(instant); // 1970-01-01T00:00:00Z

final var instant = Instant.ofEpochSecond(4102444800L, 123000000L);
System.out.println(instant); // 2100-01-01T00:00:00.123Z

System.out.println(instant.getEpochSecond()); // 4102444800
System.out.println(instant.getNano()); // 123000000

The plus... methods return a copy with the specified amount added. The minus... methods are for subtraction.

final var instant = Instant.ofEpochSecond(3000000000L, 123000000L);
System.out.println(instant); // 2065-01-24T05:20:00.123Z

final var ret1 = instant.plusSeconds(999);
System.out.println(ret1.getEpochSecond()); // 3000000999
System.out.println(ret1.getNano()); // 123000000

final var ret2 = instant.minusMillis(100);
System.out.println(ret2.getEpochSecond()); // 3000000000
System.out.println(ret2.getNano()); // 23000000

final var ret3 = instant.plusNanos(500);
System.out.println(ret3.getEpochSecond()); // 1000000000
System.out.println(ret3.getNano()); // 123000500

Conclusion

• To work with Dates and Times, you can use the APIs in the java.time package, e.g LocalDate, LocalTime, ZonedDateTime, Instant etc.
• For more code examples, please see the related posts.

Related posts

• Get the current time
• Don't use the legacy Date and Calendar classes, use new APIs instead

• API Examples
  • Calendar
  • ChronoLocalDate
  • Clock
  • Date
  • DateTimeException
  • DateTimeParseException
  • DayOfWeek
  • Duration
  • Era
    • IsoEra
    • JapaneseEra
  • Instant
  • InstantSource
  • JapaneseDate
  • LocalDate
  • LocalDateTime
  • LocalTime
  • Month
  • MonthDay
  • OffsetDateTime
  • OffsetTime
  • Period
  • Temporal
  • TemporalAccessor
  • TemporalAdjuster
  • TemporalAdjusters
  • TimeZone
  • Year
  • YearMonth
  • ZonedDateTime
  • ZoneId
  • ZoneOffset