Java 8 introduced a replacement for the old date and time classes existing in the java.util.Date package: the new java.time package, based on the Joda-Time project, designed for multiple calendar systems (the default is the ISO8601) and supporting time zone, duration, format and parsing.

The four java.time classes you must know for the exam are:

  • LocalDate: date without time
  • LocalTime: time without date
  • LocalDateTime: date and time
  • ZonedDateTime: date and time including zone info

In this post, we will refer to these classes as the four calendar classes.

The TemporalAccessor Interface

The four calendar classes have no hierarchy relationship among themselves, but they all implement the TemporalAccessor interface, that represents an arbitrary and read-only set of date and time information. This interface allows reading, in a uniform way, the individual information fields of the date and time objects:

TemporalAccessor Main Methods
int get(TemporalField field) Gets the value of the specified field
boolean isSupported(TemporalField field)  Checks if the specified field is supported.

The following example shows how to use these methods:

Creating Date and Time Objects

The four calendar classes are immutable and have no public constructors. You must use static methods like of and from to create instances of these four classes:

LocalDate Main Methods
static LocalDate of(int year, int month, int dayOfMonth) Creates an instance of LocalDate from the given data
static LocalDate from(TemporalAccessor t) Creates an instance of LocalDate from another
LocalTime Main Methods
static LocalTime of(int hour, int minute [, int second]) Creates an instance of LocalTime from the given data
static LocalTime from(TemporalAccessor t) Creates an instance of LocalTime from another
LocalDateTime Main Methods
static LocalDateTime of(int year, int month, int dayOfMonth, int hour,int minute [, int second]) Creates an instance of LocalDateTime from the provided data
static LocalDateTime from(TemporalAccessor t) Creates an instance of LocalDateTime from another
ZonedDateTime Main Methods
static ZonedDateTime of(int year, int month, int dayOfMonth, int hour, int minute, int second, int nanosecond, ZoneId zone) Creates an instance of ZonedDateTime from the provided data
static ZonedDateTime of(LocalDate date, LocalTime time, ZoneId zone) Creates an instance of ZonedDateTime from a LocalDate and a LocalTime
static ZonedDateTime of( LocalDateTime localDateTime, ZoneId zone) Creates an instance of ZonedDateTime from a LocalDateTime object
static ZonedDateTime from(TemporalAccessor t) Creates an instance of ZonedDateTime from another

Most of the previous methods throw a DateTimeException if they are unable to convert (e.g. there is no enough info in a LocalDate to create a LocalTime) or if any of the arguments is not valid (e.g. month out of range) .

Formatting and Parsing

The four classes provide the same two methods for formatting and parsing:

Calendar Classes: Formatting and Parsing Methods
String format(DateTimeFormatter formatter) Converts the calendar object to a String
static LocalDate parse(CharSequence text, DateTimeFormatter formatter) Creates a calendar object (LocalDate in this case) from a CharSequence

The DateTimeFormatter object specifies how the conversions are made. You can create your own formatters, but most often you will use any of the predefined constants provided by DateTimeFormatter. The table below shows a sample of these constants (you don’t have to know all of them for the exam but it never hurts to take a look at the official javadoc and get familiar with them).

Predefined Formatters Sample (DateTimeFormatter constants)
ISO_DATE ISO Date with or without offset 1968-05-10+01:00; 1968-05-10
ISO_LOCAL_DATE ISO Local Date  1968-05-10
ISO_LOCAL_DATE_TIME ISO Local Date and Time  1968-05-10T22:30:00
ISO_LOCAL_TIME Time without offset  22:30:00
ISO_ZONED_DATE_TIME  Zoned Date Time  1968-05-10T22:30:00 +01:00[Europe/Paris]

The calendar object you are formatting must contain all the fields (date, time and zone) required by the chosen formatter or an exception will be thrown:

In addition to the format and parse methods in the four calendar classes, DateTimeFomatter provides similar methods for parsing and formatting:

DateTimeFormatter Methods
String format(TemporalAccesor temporal) Converts the calendar object to a String
TemporalAccesor parse(CharSequence text) Creates a calendar object from a string

Notice that in this case TemporalAccessor is used for parameter and return types:

Period and Duration

The Period class is used to specify an amount of time in terms of years, months and days. Negative values are allowed as you can see in the examples below:

The Duration class is used to specify an amount of time in terms of hours, minutes, and seconds:

Both classes implement the TemporalAmount interface, so they can be used to modify calendar objects (e.g. adding or subtracting a concrete amount of time):

Leave a Reply