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.

    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 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);
    5. long hoursBetween = ChronoUnit.HOURS.between(now1, now2);
    6. long minutesBetween = ChronoUnit.MINUTES.between(now1, now2);
    8. System.out.println(hoursBetween);       // -3
    9. System.out.println(minutesBetween);     // -239

    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.         .ofLocalizedDate(FormatStyle.MEDIUM)
    3.         .withLocale(Locale.GERMAN);
    5. LocalDate xmas = LocalDate.parse("24.12.2014", germanFormatter);
    6. System.out.println(xmas);   // 2014-12-24

    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. 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. System.out.println(string);     // Nov 03, 2014 - 07:13

    Unlike the new DateTimeFormatter is immutable and thread-safe.

    For details on the pattern syntax read .