Introduction and use of [Java] LocalDate/LocalTime/LocalDateTime class


Briefly describe the background of these new date API s in JDK 1.8.
As early as in the era of JDK 1.0, JDK includes a time-dependent java.util.Date Class, and because of its own shortcomings, most of its methods were introduced in the era of JDK 1.1 Calendar Class. The Calendar class is not much better than the Date class, and it has many problems. For example:

  • The Calendar class is variable, that is, the time value stored in the internal can be modified directly, while the date time property should be more similar to the String, which is more reasonable if it has no variability.
  • The start year of Date is calculated from 1900, and the months of Date and Calendar are calculated from 0, which conflicts with the calculation methods of human intuition and other attributes. We call it offset.
  • We know that there is a SimpleDateFormat class that can format a Date, but this class can only directly operate on the Date class, not the Calendar class that later added and replaced most of the methods of the Date class.
  • None of the above classes are thread safe.

Code interpretation for the second point:

        Date date = new Date(2077,6,1); 	// Fri Jul 01 00:00:00 CST 3977
        System.out.println(date);           // Year from 1990: offset, month from 0, which means September should be 8

Note that the year of storage is not 2077, but 1900 + 2077; and the month is not June, but June January. This kind of operation logic conflicts with people's intuition.

In order to solve the above problems, a lot of new time related API s have been added in JDK 1.8: LocalDate/LocalTime/LocalDateTime, which are three of them, and the three classes this article will introduce.

Application of LocalDate/LocalTime/LocalDateTime class

From the names of these three classes, we can see that the usage difference is not too much, and the usage frequency of LocalDateTime is relatively high.


The constructors of these three classes are declared as private, source code:

private LocalDate(int year, int month, int dayOfMonth) {
        this.year = year;
        this.month = (short) month; = (short) dayOfMonth;

So when we want to get the instantiated objects of these three classes, we need to call a static method: now(), which will return an instantiated object corresponding to the current time.

This method has two overloaded methods in addition to null parameters. The overloaded method involves other new time API s, so only null parameter methods are introduced here.

        LocalDate date =;
        LocalTime time =;
        LocalDateTime dateTime =;

We can print the following for the three instanced objects, and the results are as follows:


As you can see above, the main difference between the three classes is the range of time and date recorded. Among them, local date time is the most widely used time record. Therefore, in order to avoid further discussion, only the LocalDateTime class is demonstrated, and the other two classes use the same method.

In addition to now(), there is another instantiation method: of(xxx), which can create an instantiated object at a specified time. Unlike Date, this method does not have to consider offsets.

		LocalDateTime of = LocalDateTime.of(2020, 10, 6, 13, 23, 23); // No offset
        System.out.println(of);					// 2020-10-06T13:23:23

There are many overloaded methods in this method, and it is easy to understand the difference according to the parameter name. It can be called as needed.

common method


Get the related properties and see the method name to see its function. Select a few to demonstrate as follows:

        System.out.println(dateTime.getDayOfMonth());	// 25
        System.out.println(dateTime.getDayOfWeek());	// THURSDAY
        System.out.println(dateTime.getDayOfYear());	// 177
        System.out.println(dateTime.getHour());			// 10
        System.out.println(dateTime.getMonth());		// JUNE

This method is similar to the Calendar class in use.


Setting related properties will return a reference to a new instantiated object of this class. Its function can also be seen from the method name. This is different from the Calendar direct modification itself, reflecting the immutability. See the following code for details:

        LocalDateTime localDateTime = dateTime.withDayOfMonth(22);	// On the basis of the original time, change the number of days to the 22nd day of this month
        // The storage time of the original object does not change, and a reference of the modified object is returned
        System.out.println(dateTime);		//	2020-06-25T10:10:32.928
        System.out.println(localDateTime);	//	2020-06-22T10:10:32.928


Similar to the two methods described above, look at the function of method name awareness, and increase the amount of incoming data based on the original date and time:

		LocalDateTime localDateTime2 = dateTime.plusMonths(3);	// Add 3 months to the original date
        System.out.println(localDateTime2);				// 2020-09-25T10:18:38.914
        System.out.println(dateTime);					// 2020-06-25T10:18:38.914


Subtract the amount of incoming data from the original date time.

        LocalDateTime localDateTime3 = dateTime.minusDays(3);	// Subtract 3 days from the original date
        System.out.println(localDateTime3);			// 2020-06-22T10:18:38.914
        System.out.println(dateTime);				// 2020-06-25T10:18:38.914

As can be seen from the above introduction, in fact, the methods and applications of the three classes LocalDate/LocalTime/LocalDateTime are similar to the Calendar class that existed before JDK 1.8( Introduction and use of Calendar Class )And on the basis of Calendar class, it has been mended and improved to make it more applicable.

Later, I will introduce several other new time related classes, which have close interaction with the LocalDateTime class, and I will post the link here.

Tags: JDK Java

Posted on Thu, 25 Jun 2020 00:06:45 -0400 by twistisking