Java Date Time API

Last Updated : 17 Mar 2025

The java.time, java.util, java.sql and java.text packages contains classes for representing date and time. Following classes are important for dealing with date in Java.

Java 8 Date/Time API

Java provide the date and time functionality with the help of two packages java.time and java.util. The package java.time is introduced in Java 8, and the newly introduced classes tries to overcome the shortcomings of the legacy java.util.Date and java.util.Calendar classes.

java.time.LocalDate Class

Represents a date without time, such as 2024-05-30.

Useful for representing birthdays, anniversaries, or any date-based event without the need for time.

java.time.LocalTime Class

Represents a time without a date, such as 10:15:30.

Ideal for representing times of day, such as business opening hours or train schedules.

java.time.LocalDateTime Class

Combines date and time without time zone information.

Useful for timestamping events in local time.

java.time.ZonedDateTime Class

Combines date and time with time zone information.

Useful for global timestamps that need time zone awareness.

java.time.OffsetTime Class

Represents time with a fixed offset from UTC.

java.time.OffsetDateTime Class

Represents date and time with a fixed offset from UTC.

java.time.Clock Class

Provides access to the current instant, date, and time using a time-zone.

java.time.Instant Class

Represents a moment on the timeline in nanoseconds since the epoch (1970-01-01T00:00:00Z).

java.time.Duration Class

Measures time in seconds and nanoseconds between two instants.

java.time.Period Class

Measures the amount of time in years, months, and days between two dates.

java.time.ZoneId Class

Represents a time zone ID, such as Europe/Paris.

java.time.ZoneOffset Class

Represents a time zone offset from UTC.

java.time.format.DateTimeFormatter Class

Used for parsing and formatting date-time objects.

Classical Date/Time API

But classical or old Java Date API is also useful. Let's see the list of classical Date and Time classes.

java.util.Date class
java.sql.Date class
java.util.Calendar class
java.util.GregorianCalendar class
java.util.TimeZone class
java.sql.Time class
java.sql.Timestamp class

java.util.Date Class

Represents a specific instant in time, with millisecond precision.

java.sql.Date Class

A thin wrapper around java.util.Date that allows JDBC to identify this as an SQL DATE value.

java.util.Calendar Class

Abstract class for converting between a specific instant in time and a set of calendar fields.

java.util.GregorianCalendar Class

Concrete subclass of Calendar that provides the standard calendar system used by most of the world.

java.util.TimeZone Class

Represents a time zone offset and figures out daylight savings.

java.sql.Time Class

A wrapper around java.util.Date that allows the JDBC API to identify this as an SQL TIME value.

java.sql.Timestamp Class

It extends java.util.Date class to provide nanosecond precision.

java.text.DateFormat Class

Abstract class for date/time formatting subclasses that formats and parses dates or times.

java.text.SimpleDateFormat Class

Concrete class for formatting and parsing dates in a locale-sensitive manner.

Formatting Date and Time

We can format date and time in Java by using the following classes:

Drawbacks of existing Date/Time API's

Thread Safety: The existing classes such as Date and Calendar does not provide thread safety. Hence it leads to hard-to-debug concurrency issues that are needed to be taken care by developers. The new Date and Time APIs of Java 8 provide thread safety and are immutable, hence avoiding the concurrency issue from developers.
Bad API Designing: The classic Date and Calendar APIs does not provide methods to perform basic day-to-day functionalities. The Date and Time classes introduced in Java 8 are ISO-centric and provides number of different methods for performing operations regarding date, time, duration and periods.
Difficult Time Zone Handling: To handle the time-zone using classic Date and Calendar classes is difficult because the developers were supposed to write the logic for it. With the new APIs, the time-zone handling can be easily done with Local and ZonedDate/Time APIs.

New Date Time API in Java 8

The new date API helps to overcome the drawbacks mentioned above with the legacy classes. It includes the following classes:

java.time.LocalDate: It represents a year-month-day in the ISO calendar and is useful for representing a date without a time. It can be used to represent a date only information such as a birth date or wedding date.

java.time.LocalTime: It deals in time only. It is useful for representing human-based time of day, such as movie times, or the opening and closing times of the local library.

java.time.LocalDateTime: It handles both date and time, without a time zone. It is a combination of LocalDate with LocalTime.

java.time.ZonedDateTime: It combines the LocalDateTime class with the zone information given in ZoneId class. It represents a complete date time stamp along with timezone information.

java.time.OffsetTime: It handles time with a corresponding time zone offset from Greenwich/UTC, without a time zone ID.

java.time.OffsetDateTime: It handles a date and time with a corresponding time zone offset from Greenwich/UTC, without a time zone ID.

java.time.Clock : It provides access to the current instant, date and time in any given time-zone. Although the use of the Clock class is optional, this feature allows us to test your code for other time zones, or by using a fixed clock, where time does not change.

java.time.Instant : It represents the start of a nanosecond on the timeline (since EPOCH) and useful for generating a timestamp to represent machine time. An instant that occurs before the epoch has a negative value, and an instant that occurs after the epoch has a positive value.

java.time.Duration : Difference between two instants and measured in seconds or nanoseconds and does not use date-based constructs such as years, months, and days, though the class provides methods that convert to days, hours, and minutes.

java.time.Period : It is used to define the difference between dates in date-based values (years, months, days).

java.time.ZoneId : It states a time zone identifier and provides rules for converting between an Instant and a LocalDateTime.

java.time.ZoneOffset : It describe a time zone offset from Greenwich/UTC time.

java.time.format.DateTimeFormatter : It comes up with various predefined formatter, or we can define our own. It has parse() or format() method for parsing and formatting the date time values.

Advantages of Java 8 Date/Time API

Immutability and Thread Safety

Classes in the java.time package are immutable and thread-safe by design.

Rich Set of Utilities

The API provides numerous methods to handle common date and time operations, making code more readable and maintainable.

Enhanced Time Zone Support

The java.time package includes comprehensive support for time zones with ZoneId and ZonedDateTime class.

Clarity and Precision

The new API offers more precise time measurements and clear distinctions between different types of date and time representations (for example, LocalDate vs. ZonedDateTime).

Example Usage of Java 8 Date/ Time API

Parsing and Formatting

Calculating Differences

Working with Time Zones

Conclusion

The Java 8 Date/Time API offers a more robust, intuitive, and thread-safe approach to handling date and time in Java compared to the classical Date/Time API. It addresses many of the shortcomings of the older APIs, making it easier for developers to work with date and time information effectively.