Java Date Time Tutorial

Jakob Jenkov
Last update: 2020-12-04

The Java date and time API can be rather confusing when you first try to figure out how to use it. Therefore I have put together this little trail on Java's date and time classes. Hopefully that will help you get an overview of Java's date and time classes. I also hope it may clear up some of the confusion Sun has created with Java's many date and time classes.

Actually, the Java date time API has been changed (cleaned up) in Java 8 with the introduction of a whole new set of classes. This tutorial will explain both the Java 8 date time API and the Java 7 date time API.

Java 8 Date Time API

In Java 8 a whole new date time API was added. The new Java date time API is located in the Java package java.time which is part of the standard Java 8 class library.

The main change in the Java 8 date time API is that date and time is now no longer represented by a single number of milliseconds since Jan. 1st 1970, but by the number of seconds and nanoseconds since Jan. 1st 1970. The number of seconds can be both positive and negative and is represented by a long. The number of nanoseconds is always positive and is represented by an int. You will see this new date and time representation in many of the classes in the new Java date time API.

The java.time package also contains a set of subpackages which contain more utilities etc. For instance the java.time.chrono contains classes to work with Japanese, Thai, Taiwanese and Islamic calendars. The java.time.format package contains classes used to parse and format dates from and to strings.

The core of the Java 8 date time API consists of the following classes:

Instant Represents an instant in time on the time line. In the Java 7 date time API an instant was typically represented by a number of millseconds since Jan. 1st. 1970. In Java 8 the Instant class represents an instant in time represented by a number of seconds and a number of nanoseconds since Jan. 1st 1970.
Duration Represents a duration of time, for instance the time between two instants. Like the Instant class a Duration represents its time as a number of seconds and nanoseconds.
LocalDate Represents a date without time zone information - e.g. a birthday, official holiday etc.
LocalDateTime Represents a date and time without time zone information
LocalTime Represents a local time of day without time zone information.
ZonedDateTime Represents a date and time including time zone information
DateTimeFormatter Formats date time objects as Strings. For instance a ZonedDateTime or a LocalDateTime.

Java 7 Date Time API

Java 7 has the following date and time classes and methods. Each of these classes are also explained in their own pages, later. See the links at the bottom of this page, or at the top right of every page.

System.currentTimeMillis() A static method that returns the current date and time as milliseconds since January 1st 1970
java.util.Date A class that represents a date and time. Most methods in this class are deprecated.
java.sql.Date A class that represents a date. All time information cut off. This date class is used with JDBC.
java.sql.Timestamp A class that represents a date and time. This date and time class is used with JDBC.
java.util.Calendar A base class for calendar classes. Has methods to do date and time arithmethics like adding a day or month to another date.
java.util.GregorianCalendar A concrete class subclassing java.util.Calendar, representing the Gregorian calendar which is used in most of the western world today. Has all the methods from java.util.Calendar to do date and time arithmethics.
java.util.TimeZone The Java TimeZone class is a class that represents time zones, and is helpful when doing calendar arithmetics across time zones.
java.text.SimpleDateFormat A class that can help you parse String's into Date's, and format Date's as String's.

So, which of all these classes should you use? Well, that depends on what you are trying to do.

If you need to do simple timing the System.currentTimeMillis() method will do just fine.

If you just need an object to hold a date, for instance as a property in a simple domain model object, you can use the java.util.Date class.

If you need to read and write the date and time to a database, use the java.sql.Date and java.sql.Timestamp classes.

If you need to do date calculations like adding days or months to another date, or check what weekday (monday, tuesday etc.) a given date is, or convert dates and times between time zones, use the java.util.Calendar and java.util.GregorianCalendar classes.

Here is a list of the texts in this Java date and time tutorial. This list also available in the upper right side of all pages, so you can easily navigate between them.

Jakob Jenkov

Featured Videos

Java ForkJoinPool

P2P Networks Introduction


Java Persistence
Close TOC
All Tutorial Trails
All Trails
Table of contents (TOC) for this tutorial trail
Trail TOC
Table of contents (TOC) for this tutorial
Page TOC
Previous tutorial in this tutorial trail
Next tutorial in this tutorial trail