Date API

Java 8 contains a brand new date and time API under the package java.time. The new Date API is comparable with the Joda-Time library, however it’s not the same. The following examples cover the most important parts of this new API.

Clock

Clock provides access to the current date and time. Clocks are aware of a timezone and may be used instead of System.currentTimeMillis() to retrieve the current time in milliseconds since Unix EPOCH. Such an instantaneous point on the time-line is also represented by the class Instant. Instants can be used to create legacy java.util.Date objects.

  1. Clock clock = Clock.systemDefaultZone();
  2. long millis = clock.millis();
  4. Instant instant = clock.instant();
  5. Date legacyDate = Date.from(instant);   // legacy java.util.Date

Timezones

Timezones are represented by a ZoneId. They can easily be accessed via static factory methods. Timezones define the offsets which are important to convert between instants and local dates and times.

  1. System.out.println(ZoneId.getAvailableZoneIds());
  2. // prints all available timezone ids
  4. ZoneId zone1 = ZoneId.of("Europe/Berlin");
  5. ZoneId zone2 = ZoneId.of("Brazil/East");
  6. System.out.println(zone1.getRules());
  7. System.out.println(zone2.getRules());
  9. // ZoneRules[currentStandardOffset=+01:00]
  10. // ZoneRules[currentStandardOffset=-03:00]

LocalTime

LocalTime represents a time without a timezone, e.g. 10pm or 17:30:15. The following example creates two local times for the timezones defined above. Then we compare both times and calculate the difference in hours and minutes between both times.

  1. LocalTime now1 = LocalTime.now(zone1);
  2. LocalTime now2 = LocalTime.now(zone2);
  4. System.out.println(now1.isBefore(now2));  // false
  6. long hoursBetween = ChronoUnit.HOURS.between(now1, now2);
  7. long minutesBetween = ChronoUnit.MINUTES.between(now1, now2);
  9. System.out.println(hoursBetween);       // -3
  10. System.out.println(minutesBetween);     // -239

LocalTime comes with various factory methods to simplify the creation of new instances, including parsing of time strings.

  1. LocalTime late = LocalTime.of(23, 59, 59);
  2. System.out.println(late);       // 23:59:59
  4. DateTimeFormatter germanFormatter =
  5.     DateTimeFormatter
  6.         .ofLocalizedTime(FormatStyle.SHORT)
  7.         .withLocale(Locale.GERMAN);
  9. LocalTime leetTime = LocalTime.parse("13:37", germanFormatter);
  10. System.out.println(leetTime);   // 13:37

LocalDate

LocalDate represents a distinct date, e.g. 2014-03-11. It’s immutable and works exactly analog to LocalTime. The sample demonstrates how to calculate new dates by adding or subtracting days, months or years. Keep in mind that each manipulation returns a new instance.

  1. LocalDate today = LocalDate.now();
  2. LocalDate tomorrow = today.plus(1, ChronoUnit.DAYS);
  3. LocalDate yesterday = tomorrow.minusDays(2);
  5. LocalDate independenceDay = LocalDate.of(2014, Month.JULY, 4);
  6. DayOfWeek dayOfWeek = independenceDay.getDayOfWeek();
  7. System.out.println(dayOfWeek);    // FRIDAY

Parsing a LocalDate from a string is just as simple as parsing a LocalTime:

  1. DateTimeFormatter germanFormatter =
  2.     DateTimeFormatter
  3.         .ofLocalizedDate(FormatStyle.MEDIUM)
  4.         .withLocale(Locale.GERMAN);
  6. LocalDate xmas = LocalDate.parse("24.12.2014", germanFormatter);
  7. System.out.println(xmas);   // 2014-12-24

LocalDateTime

LocalDateTime represents a date-time. It combines date and time as seen in the above sections into one instance. LocalDateTime is immutable and works similar to LocalTime and LocalDate. We can utilize methods for retrieving certain fields from a date-time:

  1. LocalDateTime sylvester = LocalDateTime.of(2014, Month.DECEMBER, 31, 23, 59, 59);
  3. DayOfWeek dayOfWeek = sylvester.getDayOfWeek();
  4. System.out.println(dayOfWeek);      // WEDNESDAY
  6. Month month = sylvester.getMonth();
  7. System.out.println(month);          // DECEMBER
  9. long minuteOfDay = sylvester.getLong(ChronoField.MINUTE_OF_DAY);
  10. System.out.println(minuteOfDay);    // 1439

With the additional information of a timezone it can be converted to an instant. Instants can easily be converted to legacy dates of type java.util.Date.

  1. Instant instant = sylvester
  2.         .atZone(ZoneId.systemDefault())
  3.         .toInstant();
  5. Date legacyDate = Date.from(instant);
  6. System.out.println(legacyDate);     // Wed Dec 31 23:59:59 CET 2014

Formatting date-times works just like formatting dates or times. Instead of using pre-defined formats we can create formatters from custom patterns.

  1. DateTimeFormatter formatter =
  2.     DateTimeFormatter
  3.         .ofPattern("MMM dd, yyyy - HH:mm");
  5. LocalDateTime parsed = LocalDateTime.parse("Nov 03, 2014 - 07:13", formatter);
  6. String string = formatter.format(parsed);
  7. System.out.println(string);     // Nov 03, 2014 - 07:13

Unlike java.text.NumberFormat the new DateTimeFormatter is immutable and thread-safe.

For details on the pattern syntax read here.