Java Date Time Tutorial
Jakob Jenkov |
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. |
TemporalAdjuster |
|
ZonedDateTime |
Represents a date and time including time zone information |
Period |
|
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.
| Tweet | |
Jakob Jenkov | |
