1. Java Date Time Tutorial
2. Java System.currentTimeMillis()
3. Java Time Measurement
4. Java's java.util.Date
5. Java's java.sql.Date
6. Java's java.sql.Timestamp
7. Java's java.util.Calendar and GregorianCalendar
8. Java's java.util.TimeZone
9. Parsing and Formatting Dates in Java
10. Java Instant
11. Java Duration
12. Java LocalDate
13. Java LocalTime
14. Java LocalDateTime
15. Java ZonedDateTime
16. Java DateTimeFormatter

• Creating a Duration
• Accessing the Time of a Duration
• Duration Calculations

A Duration object (java.time.Duration) represents a period of time between two Instant objects. The Duration class was added to the Java date time API from Java 8.

A Duration instance is immutable so once it is created you cannot change its values. You can, however, create new Duration objects based on another Duration object via calculation methods. You will see how later in this tutorial.

Creating a Duration

Creating a Duration object is done using one of the Duration class factory methods. Here is an example of how to create a Duration object using the between() method:

Instant first = Instant.now();

// wait some time while something happens

Instant second = Instant.now();


Duration duration = Duration.between(first, second);

Accessing the Time of a Duration

A Duration internally consists of two values:

• The nanosecond part of the duration
• The second part of the duration

The nanosecond part represents the part of the Duration which is smaller than a second. The second part represents the part of the Duration which is larger than one second.

Note how the Duration does not have an individual millisecond part. Only nanoseconds and seconds. This is somewhat different from what we are used to with System.getCurrentTimeMillis() where a moment in time (or a period between two moments) is represented as a number of milliseconds.

You can access these two parts of the duration using the Duration methods:

• getNano()
• getSeconds()

You can also convert the full time interval Duration to other time units like nanoseconds, minutes, hours or days. You convert a Duration to these time units using these conversion methods:

• toNanos()
• toMillis()
• toMinutes()
• toHours()
• toDays()

Each of these methods converts the full time interval represented by the Duration to either nanoseconds, milliseconds, minutes, hours or days.

The toNanos() is different from the getNano() in that the getNano() only returns the part of the Duration which is less than one second. The toNanos() method returns the full time interval converted to nanoseconds.

You might be asking yourself if there is not a toSeconds() method. There isn't because that is the same as the seconds part of the Duration. You can obtain the seconds part of the Duration using the getSeconds() method as explained earlier.

Duration Calculations

The Duration class contains a set of methods you can use to perform calculations based on a Duration object. Some of these methods are:

• plusNanos()
• plusMillis()
• plusSeconds()
• plusMinutes()
• plusHours()
• plusDays()
• minusNanos()
• minusMillis()
• minusSeconds()
• minusMinutes()
• minusHours()
• minusDays()

These methods work pretty similarly, so I will not show you how they all work. Instead I will show a plus and a minus example. That should be enough to give you an idea of how these methods work.

Duration start = ... //obtain a start duration

Duration added      = start.plusDays(3);
Duration subtracted = start.minusDays(3);

This example first creates a Duration variable named start which will be used as the base of the calculations. The actual creation of this Duration object is left out. See how to create a Duration object earlier in this tutorial.

Second, the example creates two new Duration objects based on the start Duration object. The first line creates a Duration which is equal to the start Duration plus 3 days. The second line creates Duration which is equal to the start Duration minus 3 days.

All of the calculation methods return new Duration objects representing the Duration resulting from the calculation. This is done to keep the Duration object immutable.