Java – Date and Time APIs

Java supports date and time features using primarily two packages java.time and java.util. The package java.time is added in Java 8 (JSR-310), and new added classes have aimed to solve the shortcomings of the legacy java.util.Date and java.util.Calendar classes.

1. Legacy Date Time API

1.1. Classes

The primary classes before Java 8 release were :

  • System.currentTimeMillis() : represents the current date and time as milliseconds since January 1st 1970.
  • java.util.Date : represents a specific instant in time, with millisecond precision.
  • java.util.Calendar : an abstract class that provides methods for converting between instances and manipulating the calendar fields in difefrent ways.
  • java.text.SimpleDateFormat : a concrete class for formatting and parsing dates in a locale-sensitive manner and any predefined as well as any user-defined pattern.
  • java.util.TimeZone : represents a time zone offset, and also figures out daylight savings.

1.2. Challanges

Though these APIs served the simple use cases very much, still Java community continuously complained about the problems in using these classes in an effective manner. For this reason, many other 3rd party libraries (e.g. Joda-Time or classes in Apache Commons) were more popular.

Few of the challanges were:

  • A Date class shall represent a date, but it represents an instance which has hour, minutes and seconds as well.
  • But Date doesn’t have any associated time zone. It picks up the default timezone automatically. You cannot represent a date some other timezone.
  • Classes are mutable. So that leaves additional burden on developers to clone the date before passing a function, which can mutate it.
  • Date formatting classes are also not thread safe. A formatter instance cannot be used without additional synchronization, else code may break.
  • For some reason, there is another class java.sql.Date which has timzone information.
  • Creating a date with some other timezone is very tricky and often result in incorrect result.
  • Its classes use a zero-index for months, which is a cause of many bugs in applications over the years.

2. New Date Time API in Java 8

The new date api tries to fix above problems with legacy classes. It contains mainly following classes:

  • java.time.LocalDate : 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 : 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 : handles both date and time, without a time zone. It is a combination of LocalDate with LocalTime.
  • java.time.ZonedDateTime : combines the LocalDateTime class with the zone information given in ZoneId class. It represent a complete date time stamp along with timezone information.
  • java.time.OffsetTime : handles time with a corresponding time zone offset from Greenwich/UTC, without a time zone ID.
  • java.time.OffsetDateTime : handles a date and time with a corresponding time zone offset from Greenwich/UTC, without a time zone ID.
  • java.time.Clock : 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 : 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 : Differnce 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 : To define the difference between dates in date-based values (years, months, days).
  • java.time.ZoneId : specifies a time zone identifier and provides rules for converting between an Instant and a LocalDateTime.
  • java.time.ZoneOffset : specifies a time zone offset from Greenwich/UTC time.
  • java.time.format.DateTimeFormatter : provides numerous predefined formatters, or we can define our own. It provides parse() or format() method to parsing and formatting the date time values.

3. Common Usecases

These examples use new classes introduced in Java 8 date time API.

3.1. Get Current Date and Time

All date-time classes have a factory method now() which is the preferred way to get the current date and time in Java 8.

LocalTime currentTime =;				//13:33:43.557

LocalDate currentDate =;				//2020-05-03

LocalDateTime currentDateTime =;	//2020-05-03T13:33:43.557

3.2. Parse Date and Time

Date parsing is done with the help of DateTimeFormatter class and parse() methods in date time classes.

String dateString = "2020-04-08 12:30";
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm");
LocalDateTime parsedDateTime = LocalDateTime.parse(dateString, formatter);

System.out.println(parsedDateTime);		//2020-04-08T12:30

3.3. Format Date and Time

Date formatting is done with the help of DateTimeFormatter class and format() methods in date time classes.

//Format a date
LocalDateTime myDateObj =;
DateTimeFormatter myFormatObj = DateTimeFormatter.ofPattern("dd-MM-yyyy HH:mm");

String formattedDate = myDateObj.format(myFormatObj);
System.out.println(formattedDate);	//	03-05-2020 13:46

4. More Examples

Java – Get All Dates Between Two Dates
Java 8 – Get Next and Previous Date
Java 8 – Get current date time
Java 8 – Get Current Timestamp
Java 8 – Date Comparison
Java 8 – Convert to EST Timezone
Java 8 – Measure elapsed time
Java 8 – Add days to Date
Java 8 – Difference between two dates
Java 8 – Duration Between Two Dates
Java 8 – Add or subtract N business days
Java 8 – Calculate business days between two dates
Java 8 – Calculate days between two dates
Java – Get Current User Locale
Java – Check given year is leap year or not?
Java – Parse String to Date
Java – Format XMLGregorianCalendar to ‘MM/dd/yyyy hh:mm a z’ pattern
Java – Format XMLGregorianCalendar to String
Java – Format date/timestamp in 12 hours pattern
Java – Timezone Conversion
Java – Strict Date Validation

Happy Learning !!

Was this post helpful?

Join 7000+ Fellow Programmers

Subscribe to get new post notifications, industry updates, best practices, and much more. Directly into your inbox, for free.


A blog about Java and its related technologies, the best practices, algorithms, interview questions, scripting languages, and Python.