I haven't used the Date and Time API (JSR 310 []) that came from Java SE 8 so far (since I wasn't particularly dissatisfied with Joda-Time []), but I looked it up the other day. , I found the design concept interesting, so I will write it.

Package overview

Since there are many java.time.chrono [] that contain calendars such as the Japanese calendar, the number of classes looks large.

package	Overview	interface	class	Enum	exception
java.time	Main API	0	15	2	1
java.time.chrono	Calendar such as Japanese calendar[^chrono]	6	11	4	0
java.time.format	Analysis / output	0	3	4	1
java.time.temporal	Adjust the time[^temporal]	7	6	2	1
java.time.zone	Time zone	0	4	1	1
total		13	39	13	4

java.time [] At first glance, there are many classes below, but many of them correspond to the words you usually use, so you can swallow them easily.

Year: Year []
Month: Month []
Year: YearMonth []
Date: MonthDay []
Day of the week: DayOfWeek []
Times of Day
No time zone: LocalTime []
With time zone (offset): OffsetTime []
The reason why there is no ZonedTime seems to be that the date is required to consider daylight saving time [^ 2].
Date: LocalDate []
Date and time
No time zone: LocalDateTime []
With time zone (offset): OffsetDateTime []
With time zone (zone ID): ZonedDateTime []
Period
Date: Period []
Time: Duration []
Clock: Clock []
Time point: Instant []
Think of it as a time stamp, or an abstraction of UNIX time.
Time zone
Hour, Minute, and Second Offset: [Zone Offset] []
Zone ID (Asia / Tokyo, etc.): ZoneId []

Immutable

There is only one mutable class, java.time.format.DateTimeFormatterBuilder []. Some things, such as java.time.temporal.TemporalAdjuster [], don't have to be immutable, but they kindly tell you (sour your mouth?) That you should make them immutable.

Implementation requirements: This interface does not limit the implementation to be mutable, but it is highly recommended that it be immutable.

Method naming convention

In addition to the standard get and to, the following words are used as method prefixes. You can also find with, plus, and minus in Joda-Time [].

Instance acquisition
From ʻof`: int etc.
from: From another object
Create another instance
ʻAt`: Combine to create another instance (MonthDay + Year → LocalDate, etc.)
with: Change some parts to create another instance (such as changing only the year with LocalDate # withYear ())
plus, minus: Add and subtract to create another instance

Avoid inheritance as much as possible

Most classes do not use inheritance (directly inherit from Object), with the exception of exception classes. This is in contrast to Joda-Time Joda-Time.javadoc, which made heavy use of inheritance. Even in the case of using inheritance, the abstract base class inherits Object directly, and the inherited subclass is final to avoid deep inheritance.

Thoroughly eliminate existing classes

Java.nio.Path [] introduced from Java SE 7 can be converted to each other with the existing java.io.File [] and toFile (), toPath (). I will. On the other hand, mutual conversion with the old API is implemented only on the old API side.

I got the feeling that ** you (existing class) are allowed to step on the soil of java.time **. At first, it seems that no mutual conversion was prepared [^ 1], and I even felt a grudge against the old API (ヽ ´ω`)

in conclusion

It's also written in Effective Java, but I sympathize with it because it caused unexpected bugs by not making it immutable, and I was crying because it was inherited without permission because I did not make it final. There are many places to do. I will actively use it in the future.

[^ 1]: Date and Time API Tips for Japanese (ja) --notepad