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.
Duration instance is immutable so once it is created you cannot change its values. You can, however,
Duration objects based on another
Duration object via calculation methods.
You will see how later in this tutorial.
Creating a Duration
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
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
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
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:
Each of these methods converts the full time interval represented by the
Duration to either
nanoseconds, milliseconds, minutes, hours or days.
toNanos() is different from the
getNano() in that the
only returns the part of the
Duration which is less than one second. The
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
getSeconds() method as explained earlier.
Duration class contains a set of methods you can use to perform calculations based on a
Duration object. Some of these methods are:
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
Duration object earlier in this tutorial.
Second, the example creates two new
Duration objects based on the
object. The first line creates a
Duration which is equal to the
plus 3 days. The second line creates
Duration which is equal to the
minus 3 days.
All of the calculation methods return new
Duration objects representing the
resulting from the calculation. This is done to keep the
Duration object immutable.