Java 8 Date and Time

The Date-Time package, java.time, introduced in the Java SE 8 release, provides a comprehensive model for date and time.

Why do we need for a new Date and Time library ?

Non thread-safe

The existing classes (such as java.util.Date and SimpleDateFormatter) aren’t thread-safe, leading to potential concurrency issues for users — not something the average developer would expect to deal with when writing date-handling code.  The new API avoids this issue by ensuring that all its core classes are immutable and represent well-defined values.

Poor design

Some of the date and time classes also exhibit quite poor API design. For example, years in java.util.Date start at 1900, months start at 1, and days start at 0 — not very intuitive. For example, java.util.Date represents an instant on the timeline — a wrapper around the number of milli-seconds since the UNIX epoch — but if you call toString(), the result suggests that it has a time zone, causing confusion among developers. The new API models its domain very precisely with classes that represent different use cases for Date and Time closely.

Use of third party date and time library

These issues, and several others, have led to the popularity of third-party date and time libraries, such as Joda-Time. The new API allows people to work with different calendaring systems in order to support the needs of users in some areas of the world, such as Japan or Thailand, that don’t necessarily follow ISO-8601.

Design priciples of the new Date and Time API


The methods in the API are well defined and their behavior is clear and expected. For example, invoking a Date-Time method with a null parameter value typically triggers a NullPointerException.


The Date-Time API provides a fluent interface, making the code easy to read. Because most methods do not allow parameters with a null value and do not return a null value, method calls can be chained together and the resulting code can be quickly understood. For example:


Most of the classes in the Date-Time API create objects that are immutable, meaning that, after the object is created, it cannot be modified. To alter the value of an immutable object, a new object must be constructed as a modified copy of the original. This also means that the Date-Time API is, by definition, thread-safe. This affects the API in that most of the methods used to create date or time objects are prefixed with of, from, or with, rather than constructors, and there are no set methods. For example:


The Date-Time API is extensible wherever possible. For example, you can define your own time adjusters and queries, or build your own calendar system.

Some features of date and time library (taken with some modification from

LocalDate and LocalTime

The classes which will strike in your mind probably when using the new API are LocalDate and LocalTime. These classes are local in the sense that they represent date and time from the observer’s point of view, such as a calendar in the home or a clock on the wall or a watch on wrist. There is also a composite class called LocalDateTime, which is a pairing of LocalDate and LocalTime.

Time zones, which disambiguate the contexts of different observers, are put to one side here; you should use these local classes when you don’t need that context. These classes can even be used for representing time on a distributed system that has consistent time zones.

Some Examples


The following configurations are required in order to run the application

Eclipse Mars
JDK 1.8
Have maven installed and configured

Now we will see the below steps how to create a maven based spring project in Eclipse.

Step 1. Create a standalone maven project in Eclipse

Go to File -> New -> Other. On popup window under Maven select Maven Project. Then click on Next. Select the workspace location – either default or browse the location. Click on Next. Now in next window select the row as highlighted from the below list of archtypes and click on Next button.


Now enter the required fields (Group Id, Artifact Id) as shown below

Group Id : com.roytuts
Artifact Id : java

Step 2. Modify the pom.xml file as shown below.

Step 3. If you see JRE System Library[J2SE-1.5] then change the version by below process

Do right-click on the project and go to Build -> Configure build path, under Libraries tab click on JRE System Library[J2SE-1.5], click on Edit button and select the appropriate jdk 1.8 from the next window. Click on Finish then Ok.

All the core classes in the new API are constructed by fluent factory methods. When constructing a value by its constituent fields, the factory is called of; when converting from another type, the factory is called from. There are also parse methods that take strings as parameters.


Standard Java getter conventions are used in order to obtain values from Java SE 8 classes, as shown below.


You can also alter the object values in order to perform calculations. Because all core classes are immutable in the new API, these methods are called with and return new objects, rather than using setters. There are also methods for calculations based on the different fields.


The new API also has the concept of an adjuster—a block of code that can be used to wrap up common processing logic. You can either write a WithAdjuster, which is used to set one or more fields, or a PlusAdjuster, which is used to add or subtract some fields. Value classes can also act as adjusters, in which case they update the values of the fields they represent. Built-in adjusters are defined by the new API, but you can write your own adjusters if you have specific business logic that you wish to reuse.



The new API supports different precision time points by offering types to represent a date, a time, and date with time, but obviously there are notions of precision that are more fine-grained than this.

The truncatedTo method exists to support such use cases, and it allows you to truncate a value to a field, as shown below.


Time Zones

A time zone is a set of rules, corresponding to a region in which the standard time is the same. Time zones are defined by their offset from Coordinated Universal Time (UTC). They move roughly in sync, but by a specified difference.

Time zones can be referred to by two identifiers: abbreviated, for example, “PLT,” and longer, for example, “Asia/Kolkata.” When designing your application, you should consider what scenarios are appropriate for using time zones and when offsets are appropriate.

ZoneId is an identifier for a region (see Listing 6). Each ZoneId corresponds to some rules that define the time zone for that location. When designing your software, if you consider throwing around a string such as “PLT” or “Asia/Karachi,” you should use this domain class instead. An example use case would be storing users’ preferences for their time zone.


ZoneOffset is the period of time representing a difference between Greenwich/UTC and a time zone. This can be resolved for a specific ZoneId at a specific moment in time.


Time Zone Classes

ZonedDateTime is a date and time with a fully qualified time zone. This can resolve an offset at any point in time. If you want to represent a date and time without relying on the context of a specific server, you should use ZonedDateTime.


OffsetDateTime is a date and time with a resolved offset. This is useful for serializing data into a database and also should be used as the serialization format for logging time stamps if you have servers in different time zones. OffsetTime is a time with a resolved offset.



A Duration is a distance on the timeline measured in terms of time, and it fulfills a similar purpose to Period, but with different precision. It’s possible to perform normal plus, minus, and “with” operations on a Duration instance and also to modify the value of a date or time using the Duration.



In order to support the needs using non-ISO calendaring systems, Java SE 8 introduces the concept of a Chronology, which represents a calendaring system and acts as a factory for time points within the calendaring system. There are also interfaces that correspond to core time point classes, but are parameterized by


Thanks for reading.

Leave a Reply

Your email address will not be published. Required fields are marked *

Time limit is exhausted. Please reload CAPTCHA.