Java 101: Catching up with the Java Date and Time API

Get to know the java.time classes you're most likely to use in Java 8

Page 5 of 7

LocalDate, LocalTime, and LocalDateTime

The java.time package provides LocalDate and LocalTime classes that model date and time values in an ISO calendar system and local time-zone context. They represent dates and times without taking time zones into consideration.

Use cases for local date and time classes

LocalDate and LocalTime are appropriate for use cases where time zones are irrelevant. For example, you might use LocalDate to store a birthdate or an employee hire-date, and you might use LocalTime to store the time that an alarm clock sounds its alarm.

The java.time, LocalDateTime class combines LocalDate with LocalTime, for greater precision (date plus time) than you could achieve with LocalDate or LocalTime alone.

Instantiating LocalDate, LocalTime, and LocalDateTime

There are several categories of fluent factory methods for instantiating LocalDate, LocalTime, and LocalDateTime. These categories include the following:

  • now() methods return instances created from clocks.
  • of-prefixed methods return instances created from specific values.
  • from-prefixed methods return instances created from other types (for example, obtaining a LocalDate instance from a LocalDateTime instance).

Local date and time classes: A demo

The application code in Listing 4 instantiates LocalDate, LocalTime, and LocalDateTime via some of the above fluent factory methods.

Listing 4. HumanTimeDemo.java (version 1)

import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.LocalTime;

public class HumanTimeDemo
{
   public static void main(String[] args)
   {
      // create from current date
      LocalDate localDate = LocalDate.now();
      System.out.printf("Local date = %s%n", localDate);

      // create from specific values
      localDate = LocalDate.of(2012, 12, 21);
      System.out.printf("Local date = %s%n", localDate);

      // create from 100 days into 1970
      localDate = LocalDate.ofEpochDay(100);
      System.out.printf("Local date = %s%n", localDate);
      
      // create from another local date
      localDate = LocalDate.from(localDate);
      System.out.printf("Local date = %s%n%n", localDate);


      // create from current time
      LocalTime localTime = LocalTime.now();
      System.out.printf("Local time = %s%n", localTime);

      // create from specific values
      localTime = LocalTime.of(9, 15);
      System.out.printf("Local time = %s%n", localTime);

      // create from 120 seconds past midnight
      localTime = LocalTime.ofSecondOfDay(120);
      System.out.printf("Local time = %s%n", localTime);

      // create from another local time
      localTime = LocalTime.from(localTime);
      System.out.printf("Local time = %s%n%n", localTime);


      // create from current date and time
      LocalDateTime localDateTime = LocalDateTime.now();
      System.out.printf("Local date and time = %s%n", localDateTime);
   }
}

Listing 4 reveals several ways to obtain local dates, times, and date-times. now() returns an instance based on the system clock in the default time zone; of returns an instance based on passed arguments; and from() returns an instance based on the same or another type.

Compile Listing 4 and run this application. Your output should be similar to the following:

Local date = 2013-03-23
Local date = 2012-12-21
Local date = 1970-04-11
Local date = 1970-04-11

Local time = 19:35:19.021
Local time = 09:15
Local time = 00:02
Local time = 00:02

Local date and time = 2013-03-23T19:35:19.021
| 1 2 3 4 5 6 7 Page 5